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Preface 


"me Contents of This Manual 

This manual describes the Operating System service calls that are available to 
Pascal and assembler programs. It is written for experienced Pascal 
programmers aid does not explain elementary terms and programming 
techniques. We assume that you have read the Lisa owner's Guide and 
Workshop User's Guide for the Lisa and are familiar with your Lisa system. 

Chapter 1 is a general introduction to the Operating system. 

Chapter 2 describes the File System and the available File System calls. This 
Includes a description of the interprocess communication facility, pipes, and 
the Operating System calls that allow processes to use pipes. 

Chapter 3 describes the calls available to control processes, and also describes 
the structure of processes. 

Chapter ft describes how processes can control their use of available memory. 

Chapter 5 describes the use of events and exceptions that control process 
synchronization, it also describes the use of the system clock. 

Chapter 6 describes the calls you can use to find out about the configuration 
of the system. 

Appendix A contains the source text of Syscall, the unit that contains the 
type, procedure, and function definitions discussed in this manual. 

Appendix B contains a list of system-reserved exception names. 

Appendix c contains a list of system-reserved event names. 

Appendix D contains a list of error messages that can be produced by the 
calls documented in this manual. 

Appendix E contains a description of the information you can obtain from the 
Operating System about files and devices. 

Type and Syntax Conventions 

Bold-face type is used in this manual to distinguish programming keywords and 
constructs from English text. For example, FLUSH is the name of a system 
call. System call names are capitalized in this manual, although Pascal does 
not distinguish between lower and upper case characters. Italics indicate a 
new term whose explanation follows. 
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Future Releases 

A few features of the Lisa Operating System will De changed in future 
releases: 

• Pipes will not he supported. 

• Timed events will not be supported. 

• Configuration System Calls will be changed. 

If you want your software to be upward-compatible, please take these changes 
into consideration. More information is provided in the appropriate sections 
of the manual. 
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Introduction 


The Operating System (OS) provides an environment in which multiple processes 
can coexist, communicate, and share data. It provides a file system for I/O 
and information storage, handles exceptions (software interrupts), and performs 
memory management 

Ll The Main Functions 

This chapter describes the four main functional areas of the OS: the File 
System, process management, memory management, and event and exception 
handling. 

The File System provides input and output. The File System accesses devices, 
volumes, and files. Each object, whether a printer, disk file, or any other type 
of object, is referenced by a pathname. Every I/O operation is performed as 
an uninterpreted byte stream. Using the File System, all I/O is device 
Independent. The File System also provides device-specific control operations. 

A process consists of an executing program and its associated data Several 
processes can execute concurrently by multiplexing the processor between 
them. These processes can be broken into segments which are automatically 
swapped into memory as needed. 

Memory management routines handle data segments. A data segment is a file 
that can be placed in memory and accessed directly. 

Exceptions and events are process-communication constructs provided by the 
OS. An event is a message sent from one process to another, or from a 
process to itself, that Is delivered to the receiving process only when the 
process asks for that event. An exception is a special type of event that 
forces itself on the receiving process. There is a set of system-defined 
exceptions (errors), and programs can define their own. System errors such as 
division by zero are examples of system-defined exceptions, you can use the 
system calls provided to define any exceptions you want 

1.2 Using the OS Functions 

Both built-in language features and explicit OS system calls can access OS 
routines to perform desired functions. For example, the Pascal writeln 
procedure is a built-in feature of the language. The code to execute writeln 
is supplied in IOSPASL1B, the Pascal run-time support routines library. This 
code, which is added to the program when the program is linked, calls OS 
File System routines to perform the desired output. 

You can also call OS routines explicitly. This is usually done when the 
language does not provide the operation you want OS routines allow Pascal 
programs, for example, to create new processes, which could not otherwise be 
done, since Pascal does not have any built-in process-handling functions. 
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All calls to the OS are synchronous, which means they do not return until the 
operation is complete. Each call returns an error code to Indicate If anything 
went wrong during the operatloa Any non-zero value Indicates an error or 
warning. Negative error codes Indicate warnings. For a list of error codes 
and their meaning, see Appendix D. 

13 The File System 

The File System performs all I/O as uninterpreted byte streams. These byte 
streams can go to files on disk or to other devices such as a printer or an 
alternative console. In all cases, the device or file has a File System name. 
Except for device-control functions, the File System treats devices and flies 
in the sane way. 

The File System allows sharing of all types of objects. 

The File System provides for naming objects (devices, files, etc.). A name In 
the File System Is called a pattmame A complete pathname consists of a 
directory name and a file name. The file name Is meaningful only for storage 
devices (devices that store byte streams for later use, such as disks). 

Each process has a working directory associated with it. This allows you to 
reference objects with an Incomplete pathname. To access an object in the 
working directory, you specify its file name. To access an object in a 
different directory, you specify its complete pathname. 

Before a device can be accessed, it must be mounted. Devices can be 
mounted using the Preferences tool or by using the MOUNT call. See Chapter 
2 for an explanation of this call and other File System calls. If the device is 
a storage device, the mount operation makes a volume name available. A 
volume name is a logical name for a disk, and is saved on the disk Itself. The 
mount operation logically connects the volume to the system, so that the files 
on the volume may be accessed. The volume name can replace a device name 
in a pathname used to access an object on the disk. The volume name allows 
you to access a file with the same pathname no matter where the drive is 
actually connected. 

A device can be accessed if it is specified in the configuration list created by 
the Preferences tool, is physically connected to the Lisa, aid is mounted. 

There are some operations that can be performed on unmounted devices. Two 
examples are DEVICE_CONTROL calls and scavenging. Logically mounting a 
volume on a device makes file access to the volume possible. For storage 
devices, a volume Is an actual magnetic medium that can contain recorded 
flies. For non-storage devices, volumes and files are concepts used to 
maintain a uniform Interface. Files on non-storage devices such as printers 
do not store data but act as ports for performing I/O to the devices. 
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The basic operations provided by the File system are as follows: 

mount and unmount - make a volume accessible/inaccessible 
open and close - make an object accesslble/lnaccesslble 
read and write - transfer Information to and from an object 
device control functions - control device-specific functions 

Some operations apply only to storage devices: 

allocate and deallocate - specify size of an object 
manipulate catalog - control naming of objects and creation and 
destruction of objects 

manipulate attributes - look at or change the characteristics of 
the object 

In addition to the data In an object, the object Itself has certain 
characteristics called attributes, such as the length and creation date of a 
file. Calls are available to access the attributes of any File System object. In 
addition to its system-defined attributes, an object on a storage device can 
have a label The label Is available for programs to store Information that 
they can Interpret 

Non-storage devices such as printers are accessed with a limited set of 
operations. They must be mounted and opened before they can be accessed. 
Sequential read and/or write operations are available as appropriate for the 
device. Device-control functions are available to perform any device¬ 
specific functions needed. The file-name portion of the complete pathname 
for a non-storage device Is not used by the File System, although you do have 
to provide one when you open the device. 

For storage devices, the same sequential read and write operations are valid 
as for non-storage devices. Storage devices also must be mounted, and 
particular files opened, before the files can be used. They have appropriate 
device-control functions available. 

When writing to a disk file, space for the file Is allocated as needed. Space 
for a file does not need to be contiguous, and in some cases this automatic 
allocation can result In a fragmented file, which may slow file access. To 
insure rapid access, you can pre-allocate space for the file. Pre-allocatlng 
the file also ensures that the process will not run out of space on the disk. 

Four types of objects can be stored on storage devices. These are flies, pipes, 
data segments, and event channels. Files, already discussed, are simply arrays 
of stored data Pipes are objects that provide Interprocess communication. 
Data segments are special cases of files that are loaded Into memory along 
with program code. Event channels are pipes with a specialized structure 
imposed by the system. 

m Process Management 

A process is an executing program and the data associated with it. Several 
processes can exist at one time, and they appear to run simultaneously 
because the CPU Is multiplexed among them. The Scheduler decides what 
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process should use the CPU at any one time. It uses a generally non- 
preemptive scheduling algorithm. This means that a process will not lose the 
CPU unless It Clocks. The clocked state Is explained later In this section. 

A process can lose the CPU when one of the following happens: 

• The process calls an Operating system procedure or function. 

• The process references one of Its code segments that Is not currently In 
memory. 

If neither of these occur, the process will not lose the CPU. 

Every process is started Dy another process. The newly started process is 
called the son process The process that started It is called Its fatner process 
The resulting structure is a tree of processes. See Figure 3-2 for an 
illustration of a process tree. 

When any process terminates, all Its son processes and their descendants are 
also terminated. 

When the OS Is booted. It starts a shell process The shell process starts any 
other processes desired by the user. 

Every newly created process has the same system-standard attributes and 
capabilities. These can be changed by using system calls. 

Any processes can suspend, activate, or kill any other process for which the 
global ID Is known, as long as the other process does not protect Itself. 

The memory accesses of an executing process are restricted to its own 
memory address space. Processes can communicate with other processes by 
using shared flies, pipes, event channels, or shared data segments. 

A process can be In one of three states: ready, running, or blocked. A ready 
process Is waiting for the Scheduler to select It to run. A running process Is 
currently using the CPU to execute Its code. A blocked process is waiting for 
some event, such as the completion of an I/O operation. It will not be 
scheduled until the event occurs, at which point it becomes ready. A 
terminated process has finished executing. 

Each process has a priority from l to 255. The higher the number, the higher 
the priority of the process. Priorities 226 to 255 are reserved for system 
processes. The Scheduler always runs the ready process with the highest 
priority. A process can change Its own priority, or the priority of any other 
process, while It Is executing. 

15 Memory Management 

Memory managment is concerned with what Is In physical memory at any one 
time. Each process can use up to 128 memory segments. Each segment can 
contain up to 128 Kbytes. Memory segments are of two types: code segments 
and data segments. The total amount of memory used by any one process can 
exceed the available RAM of the Lisa The Operating System will swap code 
segments In and out of memory as they are needed. To aid the Operating 
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System in swapping data segments, calls are provided to give programs the 
ability to define which data segments must be in memory while a particular 
part of the program is executing. 

You have control of how your program is divided up. For executable code 
segments, you use the segmentation commands of the Pascal compiler to break 
the program in pieces. 

In addition to residing in memory, data segments can be stored permanently 
on disk. They can be accessed with calls similar to File System calls. This 
allows you to use a data segment as a direct-access file—a file that is 
accessed as part of your memory space. 

Calls are provided for making, killing, opening, and closing data segments. 

You can also change the size of a data segment and set its access mode to 
read-only or read-write. In addition, you can make a permanent disk copy of 
the contents of a data segment at any time. Other calls give you ability to 
force the contents of the data segment to be swapped into main memory so 
they can be accessed by your process. 

1.6 Exceptions and Events 

An exception is an unexpected condition in the execution of a process (an 
Interrupt), An event is a message from another process. 

An exception can be generated either by the system or by an executing 
program. System exceptions are generated by various sorts of errors such as 
divide by zero, illegal instruction, and illegal address. System exception 
handlers are supplied that terminate the process. You can write your own 
exception handlers for any of these exceptions if you wait to try to recover 
from the error. 

user exceptions can be declared and exception handlers can be written to 
process them. Your program can then signal this new exception. 

Events are messages sent from one process to another. They are sent through 
event channels. 

A process that expects a message from an event channel executes a call to 
wait for an event on that channel. This will give it the next message, if one 
exists, or block the process until a message arrives. 

If a process wants to know when an event arrives, but does not want to wait 
for it, it can use an event-call charnel. This is set up by associating a user 
exception with the event channel when it is opened. The Operating System 
will then invoke the corresponding user exception handler whenever a message 
arrives in the event channel. 

1.7 interprocess Communication 

There are four methods for interprocess communication: shared files, pipes, 
event channels, and shared data segments. 
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Shared files are used for nicfi volume transfers of Information, it is necessary 
to coordinate the processes somehow to prevent them from overwriting each 
other's Information. 

Pipes are used for communication Between processes with an uninterpreted 
byte stream. (Note that pipes will not be supported In future releases of the 
Operating System.) The pipe mechanism provides for the needed 
synchronization; a process will block if it is trying to read from an empty 
pipe or write to a full one. A read from a pipe consumes the Information, so 
it is no longer available. Only one process can real from a given pipe. 

Event channels are similar to pipes, except that event channels transmit short, 
structured messages Instead of uninterpreted bytes. 

A shared data segment can be used to transmit a large amount of data 
rapidly. Having a shared data segment means that this data segment Is In the 
memory address spare of all the processes that want to use it All the 
processes can then directly read aid write information In the data segment. 

It Is necessary to provide some sort of synchronization to keep one process 
from overwriting another's Information. 

1.8 Using the os Interface 

The interface to all the system calls Is provided In the Syscall unit, found in 
Appendix A. This unit can be used to provide access to the calls. See the 
Workshop User's Guide for the Lisa for more information on using syscall. 

1.9 Running Programs under the os 

Programs can be written and run by using the Workshop, which provides 
program development tools such as editing and debugging facilities. 

1.10 Writing Programs That Use the OS 

You can write a program that calls OS routines to perform needed functions. 
This program uses the Syscall unit and then calls the routines needed. 
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The File System 


The File System provides device-independent I/O, storage with access 
protection, and uniform file-naming conventions. 

Device independence means that all I/O is performed in the same way, 
whether the ultimate destination or source is disk storage, another program, a 
printer, or anything else, in all cases, I/O is performed to or from files, 
although those files can also be devices, data segments, or programs. 

Every file is an uninterpreted stream of eight-bit bytes. 

A file that is stored on a block-structured device, such as a disk, is listed in 
a catalog ^also called a director^ and has a name. For each such file the 
catalog contains an entry describing the file's attributes. Including the length 
of the file, its position on the disk, and the last backup copy date. Arbitrary 
application-defined information can be stored in an area called the file lade! 
Each file has two associated measures of length, the Logical End of File 
(LEOFJ and the Physical End of File (PEOF) The LEOF is a pointer tu the last 
byte that has meaningful data. The PEOF is a count of the number of blocks 
allocated to the file. The pointer to the next byte to be read or written is 
called the file marker. 

Since I/O is device independent, application programs do not have to take 
account of the physical characteristics of a device. However, on block- 
structured devices, programs can make I/O requests in whole-block increments 
in order to improve program performance. 

All input and output is synchronous in that the I/O requested is performed 
before the call returns. The actual I/O, however, is asynchronous, in that 
processes may block when performing I/a See Section 3.5, Process Scheduling, 
for more information on blocking. 

To reduce the impact of an error, the File System maintains distributed, 
redundant information about the files on storage devices. Duplicate copies of 
critical information are stored in different forms and in different places on 
the media All the files are able to identify and describe themselves, and 
there are usually several ways to recover lost information. The Scavenger 
utility is able to reconstruct damaged catalogs from the information stored 
with each file. 

2.1 File Names 

All the files known to the Operating System at a particular time are organized 
into catalogs. Each disk volume has a catalog that lists all the files on the 
disk. 

Any object catalogued in the File System can be named by specifying the 
volume on which the file resides and the file name. The names are separated 
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by the character Because the top catalog in the system has no name, all 
complete pathnames begin with 

For example, 

-LISA-FORMAT.TEXT 

refers to a file named FORMAT.TEXT on a volume named LISA. The file 
name can contain up to 32 characters, if a longer name is specified, the 
name is truncated to 32 characters. Accesses to sequential devices use an 
arbitrary dummy filename that is ignored but must be present in the 
pathname. For example, the serial port pathname 

-RS232B 


is insufficient, but 


-RS232B-XYZ 


is accepted, even though the -XYZ portion is Ignored. Certain device names 
are predefined: 


RS232A 

RS232B 

PARAPORT 

SLOTxCHANy 

MAINCONSOLE 

ALTCONSOLE 

UPPER 

LOWER 

BITBKT 


Serial Port A 
Serial Port B 
Parallel Port 

Serial ports: x is 1, 2, or 3 and y is 1 or 2 
writeIn and readln device 
writeln and readln device 
upper Diskette drive (Drive l) 

Lower Diskette drive (Drive 2) 

Bit bucket: data is thrown away when directed here 


See Chapter 6 for more information on device names. 


upper and lower case are not significant in pathnames: 'TESTVOL' Is the same 
object as ‘Testvol’. Any ASCII character is legal in a pathname. Including 
non-printing characters and blank spaces. However, use of ASCII 13, 
RETURN, In a pathname Is strongly discouraged. 

22 The Working Directory 

It is sometimes inconvenient to specify a complete pathname, especially when 
working with a group of files in the same volume. To alleviate this problem, 
the Operating System maintains the name of a working directory for each 
process. When a pathname is specified without a leading the name refers 
to an object in the working directory. For example, if the working directory 
is -LISA the name FORMAT.TEXT refers to the same file as 
-LISA-FORMAT.TEXT. The default working directory name Is the name of the 
boot volume directory. 


You can find out what the working directory is with GETWORKINGDIR. 
You can change to a new working directory with SET_W0RKING_DIR. 
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23 Devices 

Device names follow tne same conventions as file names. Attributes like baud 
rate are controlled by using the DEVICE_CCNTROL call with the appropriate 
pathname. 

Each device has a permanently assigned priority. From highest to lowest, the 
priorities are: 

Power on/off button 
Serial port A (RS232A) 

Serial port B (RS232B, the leftmost port) 

I/O slot l 
I/O slot 2 
I/O slot 3 

Keyboard, mouse, battery-powered clock 

10 ms system timer 

CRT vertical retrace interrupt 

Parallel port 

Diskette 1 (UPPER) 

Diskette 2 (LOWER) 

Video screen 

The device driver associated with a device contains information about the 
device’s physical characteristics such as sector size and Interleave factors for 
disks. 

2.4 Storage Devices 

On storage devices such as disk drives, the File System reads or writes file 
data in terms of pages. A pagels the same size as a block. Any access to 
data in a file ultimately translates into one or more page accesses. When a 
program requests an amount of data that does not fit evenly into some 
number of pages, the File system reads the next highest number of whole 
pages. Similarly, data is actually written to a file only in whole page 
Increments. 

A file does not need to occupy contiguous pages. The File System keeps 
track of the locations of all the pages that make up a file. 

Each page on a storage device is self-identifying; the page descriptor is stored 
with the page contents to reduce the destructive Impact of an 1/0 error. 

The eight components of the page descriptor are: 

Version number 

volume identifier 

File identifier 

Amount of data on the page 

Page name 

Page position in the file 
Forward link 
Backward link 
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Each volume has a Medium Descriptor Data File (MDDF) which describes the 
various attributes of the medium such as Its size, page length, block layout, 
and the size of the boot area. The MDDF is created when the volume Is 
initialized. 

The File system also maintains a record of which pages on the medium are 
currently allocated, and a catalog of all the files on the volume. Each file 
contains a set of file hints, which describe end point to the actual file data. 

2.5 The Volume Catalog 

On a storage device, the volume catalog provides access to the flies. The 
catalog Is itself a file that maps user names into the internal file identifiers 
used by the Operating System. Each catalog entry contains a variety of 
information about each file including: 

Name 

Type 

Internal file number and address 
Size 

Date and time created, last modified, and last accessed 
File identifier 
Safety switch 

The safety switch is used to avoid accidental deletions. While the safety 
switch is on, the file cannot be deleted. The other fields are described under 
the LOCKUP File System call. 

The catalog can be located anywhere on the medium. 

2.6 Labels 

An application can store its own information about a file in an area called 
the file latel The label allows an application to keep the file data separate 
from information maintained about the file. Labels can be used for any 
object In the File System. The maximum label size Is 128 bytes. I/O to labels 
is handled separately from file data I/a 

2.7 Logical and Physical End of File 

A file contains some number of bytes of data recorded in some number of 
physical pages. Additional pages which do not contain any file data can be 
allocated to the file. There are, therefore, two measures of the end of the 
file. The Logical End of File (LEOF) is a pointer to the last stored byte that 
has meaning to the application. The Physical End of File (PEOF) is a count of 
the number of pages allocated to the file. 

in addition, each open file has a pointer called the file marker which points 
to the next byte in the file to be read or written. When the file is opened, 
the file marker points to the first byte (byte number 0). The file marker can 
be positioned automatically or explicitly using the read and write calls. For 
example, when a program writes to a file opened with Append access, the file 
marker is automatically positioned to the end of the file before new data are 
written. The file marker cannot be positioned past LEOF except by a write 
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operation that appends data to a file; In this case the file marker Is 
positioned one byte past LEOF. 

When a file is created, an entry for it Is made in the catalog specified In its 
pathname, but no space Is allocated for the file Itself. When the file is 
opened by a process, space can be allocated explicitly by the process, or 
automatically by the Operating System, if a write operation causes the file 
marker to be positioned past the LEOF marker, LEOF (and PEOF if necessary) 
are automatically extended. The new space is contiguous if possible. 

2.8 File Access 

The File System provides a device-independent bytestream interface. As far 
as an application program is concerned, a specified number of bytes Is 
transferred either relative to the file marker or at a specified byte location 
In the file. The physical attributes of the device or file are not Important to 
the application, except that devices that do not support positioning can 
perform only sequential operations. Programs can sometimes Improve 
performance, however, by taking advantage of a device's physical 
characteristics. 

Programs can request any amount of data from a file. The actual I/O, 
however. Is performed In whole-page Increments when devices are block 
structured. Therefore, programs can optimize I/O to such devices by setting 
the file marker on a page boundary and making I/O requests in whole-page 
Increments. 

A file can be open for access by more than one process concurrently. All 
requests to write to the file are completed before any other access to the file 
Is permitted. When one process writes to a file, the effect of the write 
operation is immediately available to all other processes reading the file. The 
other processes may, however, have accessed the file in an earlier state. 

Data already obtained by a program are not changed. The programmer must 
ensure that processes maintain a consistent view of a shared file. 

When you open a file, you specify the kind of access allowed on the file. 

When the file is opened, the Operating System allocates a file marker for the 
calling process and a run-time identification number called the refnum The 
process must use the refnum in subsequent calls to refer to the file. Each 
operation using the refnum affects only the file marker associated with that 
refnum. 

Processes can share the same file marker. In global access mode, each 
process uses the same refnum for the file. When a process opens a file In 
global access mode, the refnum it gets back can be passed to any other 
process, and used by any process. Note that any number of processes can 
open a file with Global_Refnum, but each time the OPEN call Is used a 
different refnum is produced. Each of those refnums can be passed to other 
processes, and each process using a particular refum shares the same file 
marker with other processes with the same refum. Processes using different 
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refnums, however, always have different file markers, whether or not those 
refnums were obtained with GlobalRefnum. 

A file can also be opened in private mode, which specifies that no other OPEN 
calls are to be allowed for that file. A file can be opened with 
Global_Refnum and private, which opens the file for global access, but allows 
no other process to open that file. By using this call, processes can control 
which other processes have access to a file. The opening process passes the 
global refnum to any other process that is to have access, and the system 
prevents other processes from opening the file. 

Processes using global access may not be able to make any assumptions about 
the location of the file marker from one access to the next. 

2.9 Pipes 

Because the Operating System supports multiple processes, a mechanism is 
provided for interprocess communication. This mechanism is called a pipe 
Pipes are similar to the other objects in the File System -- trey are named 
according to the same rules, and they can have labels. 

_ NOTE _ 

Pipes will not be supported in future releases of the operating System. 

Do not use the pipe mechanism If you want your software to be 
upward-compatible. 


As with a file, a pipe is a byte stream. With a pipe, however, information is 
queued in a first-ln-flrst-out manner. Also, a pipe can have only one reader 
at a time, and once data is read from a pipe it is removed from the pipe. 

A pipe can be accessed only in sequential mode. Although only one process 
can read data from a pipe, any number of processes can write data into it. 
Because the data read from the pipe is consumed, the file marker is always at 
zero. If the pipe is empty and no processes have it open for writing, EOF (End 
Of File) is returned to the reading process. If any process has the pipe open 
for writing, the reading process is suspended until enough data to satisfy the 
call arrives in the pipe, or until all writers close the pipe. 

When a pipe is created, its size is 0 bytes, unlike with ordinary files, the 
initializing program must allocate space to the pipe before trying to write 
data into It To avoid deadlocks between the reading process and the writers, 
the Operating System does not allow a process to read or write an amount of 
data greater than half the physical size of the pipe. For this reason, you 
should allocate to the pipe twice as much space as the largest amount of data 
in any planned read or write operation. 

A pipe is actually a circular buffer with a read pointer and a write pointer. 

All writers access the pipe through the same write pointer. Whenever either 
pointer reaches the end of the pipe, it wraps back around to the first byte. If 
the read pointer catches up with the write pointer, the reading process blocks 


2-6 



Operating System Reference Manual 


The File System 


until data are written or until all tne writers close tne pipe. Similarly, If tne 
write pointer catches up with the read pointer, a writing process blocks until 
the pipe reader frees up some space or until the reader closes the pipe. 
Because pipes have this structure, there are restrictions on some operations. 
These restrictions are discussed with the relevant File System calls. 

Processes can never make read or write requests bigger than half the size of 
the pipe because the Operating System always fully satisfies each read or 
write request before returning to the program. In other words, if a process 
asks for 100 bytes of data from a pipe, the Operating System waits until there 
are 100 bytes of data in the pipe and then completes the call. Similarly, If a 
process tries to write 100 bytes of data into a pipe, the Operating System 
waits until there is room for the full 100 bytes before writing anything into 
the pipe. If processes were allowed to make write or read requests for 
greater then half of a particular pipe, it would be possible for a reader and a 
writer to deadlock, with neither having room in the pipe to satisfy its 
requests. 

2.10 File System Calls 

This section describes all the Operating System calls that pertain to the File 
System. A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used in the File System calls: 

Pathname = STRING[hax_Pathname]; (* hax Pathname = 255 *) 

EName = STRING[hax_Ename]; (» ttax_EName = 32 *) 

Accesses = (Dread, Dwrite, Append, Private, Global Refnum); 

HSet = SET OF Accesses; 

Iohode = (Absolute, Relative, Sequential); 

The Fs lnfo record and its associated types are described under the LOOKUP 
call. The Detype record is described under the DEVICE_C0NTR0L call. 
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2 . 10.1 MAKE_FILE and MAKE_PIPE File System Calls 

MAKE FILE (Var Ecocte: Integer; 

Var Path:Pathname; 

LabeljSize:Integer) 

MAKEPIPE (Var Ecode: Integer; 

Var Path:Pathname; 

Label_Size:Integer) 

Ecode: Error indication 

Path: Name of new object 

Label_Size: Number of bytes for the object's label 

MAKE_FILE and MAKE_PIPE create the specified type of object with the 
given name. If the pathname does not specify a directory name (more 
specifically. If the pathname does not begin with a dash), the working 
directory is used. LabelSize specifies the initial size in bytes of the label. 
It must be less than or equal to 128 bytes. The label can grow to contain up 
to 128 bytes no matter what its initial size. er\y error indication is returned 
in Ecode. 


_ NOTE _ 

Pipes will not be supported in future releases of the Operating System. 
Do not use the pipe mechanism if you want your software to be 
upward-compatible. 


The MAKE_FILE example on the next page checks to see whether the 
specified file exists before opening it 
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CONST FileExiStS = 890; 

VAR FileRefNum, ErrorCode:INTEGER; 

Fi leName: PatfiName; 

Happy:BOOLEAN; 

Response:CHAR; 

BEGIN 

Happy:"FALSE; 

VHILE NOT Happy DO 
BEGIN 

REPEAT (« get a file name *) 

•RITE('File name: 

READLN(F i leName ); 

UNTIL LENGTH(FileName)>0; 

MAKE_FILE(ErrorCode,FileName,0); (*no label for this file*) 
IF (ErrorCode<>0) THEN (* does file already exist? *) 

IF (ErrorCode=FileExists) THEN (* yes ») 

BEGIN 

KRITE(FlleNarae,' already exists. Overwrite? '); 
READLN(Response); 

Happy .-"(Response IN [ 'y', 'Y' ]); (*go ahead and overwrite*) 
END 

ELSE WIITELNCError *,ErrorCode,' while creating file.') 
aSE Happy: =TRUE; 

END; 

0PEN(ErrorCode„ Filename. FileRefNum, [Dwrite]); 

END; 
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2.102 KILLOBJECT File System Call 

KILL_OBJECT (Var Ecode:Integer; 

Var Path:Pathname) 

Ecode: Error Indicator 

Path: Name of object to be deleted 

KlLL_OBJECT deletes the object given in Path from the File System. Objects 
with the safety switch on cannot be deleted. If a file or pipe is open at the 
time of the KILLOBJECT call, its actual deletion is postponed until it has 
been closed by all processes that have it opea During this period no new 
processes are allowed to open it. The object to be deleted need not be open 
at the time of the KILL OBJECT call. A KILL OBJECT call can be reversed 
by LNKILL_FILE, as long as the object is a file and is still open. 

The following program fragment deletes files until RETURN is pressed: 

CONST FlleNotFound=894; 

VAR FileName:PathName; 

Errorcode:INTEGER; 

BEGIN 

REPEAT 

KRITE('File to delete: '); 

READLN(FileName); 

IF (FileName<>*’) THEN 
BEGIN 

KILLOBJECT (Errorcode, Filename); 

IF (Error0ode<>0) THEN 
IF (Errorcode =FileNotFound) THEN 
•RITELN(FileName,' not found.') 

ELSE KRITELN('Error ',Errorcode,' while deleting file.') 
ELSE VRlTELN(FlleName,' deleted.'); 

END 

UNTIL (FileName=") ; 

END; 
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zio.3 UNKILL FILE File System call 

UNKILL_FILE (Var Ecode:Integer; 

RefNum:Integer; 

Var Newname:e_name) 

Ecode: Error indicator 

RefNum: Refnum of the killed and open file 

Newname: New name for the file being restored 

UNKILL_F1LE reverses the effect of KILLJBJECT as long as the killed 
object is a file that is still open. A new catalog entry is created for the file 
with the name given in Newname. Newname is not a full pathname: the 
resurrected file remains in the same directory. 
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Z.10L4 RENAMEENTRY File System Call 

RENAMEENTRY (Var Ecode:integer; 

var Path: Pathname; 

Var Newname:E_Name) 

Ecode: Error Indicator 

Path: Object's old name 

Newname: Object's new name 

RENAMEJENTRY changes the name of an object In the File System. 

Newname cannot be a full pathname. The name of the object Is changed, but 
the object remains In the same directory. The following program fragment 
changes the file name of F0RMATTER.L1ST to NEWFORMAT.TEXT. 

VAR OldName:PathName; 

Ne*Name:E_Name; 

Errorcode:INTEGER 
BEGIN 

01dName: = '-LISA-F0RHATTER.LIST*; 

NewName: =' NEVFORMAT. TEXT ‘ ; 

RENAME_ENTRY(Errorcode,OldName,NewName); 

END; 

The file's full pathname after renaming Is 
-L1SA-NEWF0RMAT.TEXT 

Volume names can be renamed by specifying only the volume name In Path. 
Here is a sample program fragment which changes a volume name. Note that 
the leading dash (-), given In CfldName, Is not given in NewName. 

VAR OldName:Pathname; 

NewName:E_Name; 

ErrorOode:INTEGER 
BEGIN 

OldName:=*-thomas* ; 

NewName :='steams ‘ ; 

RENAME ENTRY (Errorcode, OldName, NewName); 

END; 
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2.10.5 LOOKUP File System Call 

LOOKUP (Var Ecode:Integer; 

Var Path:Pathname; 

Var Attributes:Fs_Info) 

Ecode: Error indicator 

Path: Object to lookup 

Attributes: Information returned about path 

LOOKUP returns information about an object in the file system. For devices 
and mounted volumes, call LOOKUP with a pathname that names the device or 
volume without a file name component: 

DevName:=*-UPPER’; (* Diskette drive l *) 

LOOKUP ( E r rorCode, DevName, infoRec); 

If the device is currently mounted and is block structured, all of the record 
fields of Attributes contain meaningful values; otherwise, some values are 
undefined. 

The Fsjnfo record Is defined as follows. The meanings of the Information 
fields are given in Appendix E. 

FSInfO = RECORD 

name: e_name; 
devnum: INTEGER; 

CASE OType:info_type OF 

device t, volumet: 

(iocharmel: INTEGER 
devt: devtype; 

Slotno: INTEGER; 

fs_size: LONGINT; 

VOl_slze: LONGINT; 
blockstructured, 
mounted: BOOLEAN; 

opencount: LONGINT; 
prlvatedev, 
remote, 

lockeddev: BOOLEAN; 
mount.pending, 
unmount_pendlng: BOOLEAN; 
volname, 

password: e_name; 

fsversion, 

volid, 

volnum: INTEGER; 
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blocksize, 

datasize, 

clustersize 

filecount: INTEGER;(“Number of files on vol*) 

freecount: LONGINT; (“Nuntoer of free blocks *) 

DTVC, (• Date Volume Created “) 

DTVB, (* Date Volume last Backed up *) 

DTVS:LONGINT;(* Date Volume last scavenged “) 

Machine_id, 

overmountstamp, 

master_copy_id: LONGINT; 

privileged, 

•rite_protected: BOOLEAN; 

master, 

copy, 

scavenge flag: BOOLEAN); 
objectt: ( 

size: LONGINT; (^actual no of bytes written *) 
psize: LONGINT; (“physical size in bytes *) 
lpsize: INTEGER; (“Logical page size in bytes *) 
ftype: filetype; 

etype: entrytype; 

DTC, (* Date Created *) 

DTA, (“ Date last Accessed *) 

DTH. (“ Date last Modified *) 

DTB: LONGINT; (« Date last Backed up “) 

refnum: INTEGER; 

fmark: LONGINT; (“ file marker “) 

acmode: mset; (* access mode *) 

nreaders, (• Number of readers *) 
writers, (* Number of writers *) 
nusers: INTEGER; (“ Number of users *) 

fuid: uid; (* unique identifier “) 

eof, (* EOF encountered? **) 

safety_on, (* safety switch setting *) 

kswitch: BOOLEAN; (* has file been killed? *) 
private,(* File opened for private access? *) 
locked, (* Is file locked? *) 
protected:B00LEAN);(* File copy protected? «) 

END; 
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Uld = INTEGER; 

InfoType = (device_t, volume s object_t); 

Devtype = (diskdev, pascalbd, seqdev, bltbkt, non_lo); 

Filetype = (undefined, MDOFFile, rootcat, freelist, 

badblocks, sysdata, spool, exec, usercat, pipe, 
bootflie, swapdata, swapcode, ramap, userflle, 
killedobject); 

Entrytype - (enptyentry, catentry, linkentry, fileentry, 
plpeentry,ecentry, kllledentry); 

Tne eof field of tne Fs_lnfd record Is set after an attempt to read more 
bytes than are available from the file marker to the logical end of the file, or 
after an attempt to write when no disk space Is available. If the file marker 
Is at the twentieth byte of a twenty-five byte file, for example, you can 
read up to 5 bytes without setting eof, but If you try to read 6 bytes, tne 
File System gives you only 5 bytes of data and eof Is set 

The following program reports how many bytes of data a given file has: 

VAR lnfoRec:Fs_lnfo;("information returned by LOOKUP and INFO*) 
Filename:Pathname; 

ErrorCodeINTEGER; 

BEGIN 

VRITECFlle: *); 

REACLN(FileName); 

L0OKUP(ErrorCode,Filename.infoRec); 

IF (ErrorCode<>o) THEN 
*RITELN(‘Cannot lookup ',FiieName) 

ELSE 

HRITELN(FlleName,* has ', InfoRec. Size,’ bytes of data.’),- 
END; 
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2.106 INFO File System Call 

INFO (Var Ecode:Integer; 

RefNun: Integer; 

Var Reflnfo:Fs_Info) 

Ecode: Error Indicator 

Ref Nun: Reference number of object in File System 

Refinfo: Information returned about RefNum's object 

INFO serves a function similar to that of LOOKUP but is applicable only to 
objects In the File System that are open. The definition of the Fsjnfo 
record is given under LOOKUP and In Appendix A. 
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2.10.7 SETFILEINFO File System Call 

SET_FILE_INFO ( Var Ecodeinteger; 

RefNum:Integer; 

Fsi:Fs_lnfo) 

Ecode: Error indicator 

RefNum: Reference number of object in File system 

Fsi: New information about tne object 

SET_FILE_INFO changes the status information associated with a given object. 
This call works in exactly the opposite way that LOOKUP and INFO work, in 
that the status information is given by your program to SET_FILE_INFa The 
Fsl argument is the same type of information record as that returned by 
LOOKUP and INFQ The object must be open at the time this call is made. 

The following fields of the information report may be changed: 

flle_scavenged 
flle_closed by_OS 
file_left_open 
usertype 
user_subtype 
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2.108 OPEN File System Call 

OPEN (Var Ecode:integer; 

Var Path .-Pathname; 

Var RefNum:Integer; 

nanlprnset) 

Ecode: Error indicator 

Path: Name of object to be opened 

RefNum: Reference number for object 

Manip: Set of access types 

The OPEN call opens an object so that it can be read or written to. When 
you call OPEN, you specify the set of accesses that will be allowed on that 
file or sequential device. The available access types are: 

• Dread -- Allows you to read the file 

• Dwrite — Allows you to write in the file (to replace existing 
data) 

• Append — Allows you to add on to the end of the file 

• Private — Prevents other processes from opening the file 

• GlobalRefnum — creates a refnum that can be passed to other 
processes 

Note that you can give any number of these modes simultaneously. If you 
specify Dwrite and Append in the same OPEN call, Dwrtte access will be used. 
See Section 2.8 for more information on Global Refnum and Private access 
modes. 

If the object opened already exists and the process calls WRITE_DATA 
without having specified Append access, the object can be overwritten. The 
Operating System does not create a temporary file and wait for the 
CLOSEJBJECT call before deciding what to do with the old file. 

An object can be opened by two separate processes (or more than once by a 
single process) simultaneously. If the processes write to the file without using 
a global refnum, they must coordinate their file accesses so as to avoid 
overwriting each other's data 

Pipes cannot be opened for Dwrite access. You must use Append if you want 
to write into the pipe. To set up a private pipe, the reader process opens the 
pipe first, specifying Dread mode; the writer process then opens the pipe with 
Append. Private access mode. 
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2.10.9 CLOSEJBJECT File System Call 

CLOSE_0BJECT (Var Ecode:Integer; 

RefNum:Integer) 

Ecode: Error indicator 

RefNum: Reference number of object to be closed 

If RefNum Is not global, CLOSE JJBJECT terminates any use of RefNum for 1/0 
operations. A FLUSH operation Is performed automatically and the file Is 
saved in Its current state. If RefNum Is a global refrtum and other processes 
have the file open, RefNum remains valid for these processes and other 
processes can still access the file using RefNum. 

The following program fragment opens a file, reads 512 bytes from It, and 
then closes the file. 

TYPE Byte=-128..127; 

VAR Filename:PathName; 

ErrorCode, FileRefNuncInteger; 

ActualBytes:Longlnt; 

Buffer:ARRAY[0..511] OF Byte; 

BEGIN 

OPEN(ErrorOode, FileName, F lleRefNunt [DRead]); 

IF (Error0ode>0) THEN 
M1ITELN(‘Cannot open FileName) 

ELSE 

BEGIN 

READ_DATA(ErrorCode, 

FileRefNum, 

ORDA(aBuffer), 

512, 

ActualBytes, 

Sequential, 

0 ); 

IF (ActualBytes<512) THEN 

•RITE('0nly read ActualBytes, ‘ bytes from *, FileName); 
CLOSE JOBJECT (ErrorCode, FileRefNum); 

END; 

END; 
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2 . 10.10 READJDATA and WRI7E_DATA File system calls 

READDATA (Var Ecode ^nteger.- 
RefNuunlnteger; 

DataAddr: Longlnt; 

Count .-Longlnt; 

Var Actual:LongInt; 
node:IoMode; 

Offset:Longlnt); 


•RITEDATA (Var Ecode integer; 

RefHum:Integer; 
Data_Addr: Longing- 
Count: Longlnt; 

Var Actual: Longl n^- 
tlode^oflode; 
Offset:Longlnt); 


Ecode: 

RefNum: 

Data_Addr: 

Count: 

Actual: 

Mode: 

Offset: 


Error Indicator 

Reference number of object for I/O 
Address of data (source or destination) 
Number of bytes of data to be transferred 
Actual number of bytes transferred 
I/O mode 

Offset (absolute or relative modes) 


READJDATA reads Information from the device, pipe, or file specified by 
RefNum, and WRITEJDATA writes Information to It. Data Addr Is the 
address for the destination or source of Count bytes of data. The actual 
number of bytes transferred Is returned In Actual. 

Mode can be absolute, relative, or sequential, in absolute mode. Offset 
specifies an absolute byte of the file, in relative mode. Offset specifies a 
byte relative to the file marker, in sequential mode. Offset Is Ignored 
(assumed to be zero); transfers occur relative to the file marker. Sequential 
mode (which Is a special case of relative mode) Is the only access mode 
allowed for reading or writing data In pipes or sequential (non-disk) devices. 
Non-sequentlal modes are valid only on devices that support positioning. The 
first byte is numbered 0. 

if a process attempts to write data past the Physical End of File on a disk 
file, the Operating System automatically allocates enough additional space to 
contain the data. This new space, may not be contiguous with the previous 
blocks. You can use the ALLOCATE call to ensure that any newly allocated 
blocks are located next to each other, although they may not be located near 
the rest of the file. 

READ DATA from a pipe that does not contain enough data to satisfy Count 
suspends the calling process until the data arrives in the pipe. If there are no 
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writers, the end-of-flle Indication (error 848) Is returned In Ecode. Because 
pipes are circular, WRITEDATA to a pipe with insufficient room suspends the 
calling process (the writer) until enough space Is available (until the reader 
has consumed enough data). If no process has the pipe open for reading and 
there Is not enough space In the pipe, the end-of-flle Indication (848) Is 
returned In Ecode. 


_ NOTE _ 

READ_DATA from the MAINCONSOLE or altconsole devices must 
specify Count - 1. 


The following program copies a file. Note that you must supply the correct 
location for Syscall in the second line of the program. 

PROGRAM CopyFile; 

USES ("Syscall.Obj») SysCall; 

TYPE By te=-128..127; 

VAR OldFile,NenFlle:PathName; 

OldRefNurn, NewRefNum: INTEGER; 

BytesRead,Bytesiritten:L0NGINT; 

ErrorCode INTEGER; 

Response:CHAR; 

Buffer:ARRAY [0..511] OF Byte; 

BEGIN 

iRITE('File to copy: '); 

READLN(OldFlle); 

OPEN(ErrorCode, OldFile, OidRefNunt [DRead]); 

IF (ErrorCode>0) THEN 
BEGIN 

•RITELNCError ',ErrorCode,' while opening ',OldFile); 
EXIT(CopyFile); 

END; 

VRlTE('Ne» file name: ’); 

READLN(NewFile); 

MAKE FILE(ErrorCode, NewFile, 0); 

OPEN(ErrorCode,NewFile,NewRefNum [Dirite]); 

REPEAT 

READ_DATA( ErrorCode, 

OidRefNunt 

0RD4(aeuffer), 

512, BytesRead, sequential, 0); 

IF (ErrorCode=0) AND (BytesReaOO) THEN 
•RITE DATA (ErrorCode, 

NewRefNunt 

0RD4(aeuffer), 

BytesRead, Bytesiritten, Sequential, 0); 

UNTIL (BytesRead=0) OR (Bytesiritten=o) OR (ErrorCode>0); 
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IF (Errorcode>0) THEN 

*RITELN('File copy encountered error ',ErrorCode); 
CLOSE_OBJECT(ErrorCode,NewRefNum); 

CLOSE JOBJECT (ErrorCode, OldRefNum); 

END. 
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2.10.11 reao_LABEL and WRITE_label File system calls 

READ_LA0EL (Var Ecode:integer; 

Var Path:Pathname; 

DataAddr: Longlnt; 

Count :LongIrrt; 

Var Actual:Longlnt) 

•RITE LA8EL (var Ecocte:Integer; 

Var Path:Pathname; 

Data_Addr:Longing- 
Count-.Longlnt; 

Var Actual:Longlnt) 


Ecode: 

Path: 

Data_Addr: 
Count: 
Actual: 


Error Indicator 

Name of object containing the label 
Source or destination of I/O 
Number of bytes to transfer 
Actual number of bytes transferred 


These calls read or write the label of an object In the File System. I/O 
always starts at the beginning of the label. Count Is the number of bytes the 
process wants transferred to or from DataAddr, and Actual is the actual 
number of bytes transferred. An error Is returned if you attempt to read 
more than the maximum label size, 128 bytes. 
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2.10.12 DEVICE_CONTRCL File System Call 

DEVICEJ30N1R0L (Var Ecode: integer; 

Var Path:Pathname; 

Var CParm:Dctype) 

Ecode: Error indicator 

Path: Device to he controlled 

CParm: A record of information for the device driver 

DEVICE CONTROL Is used to send device-specific information to a device 
driver or to obtain device-specific information from a device driver. 

Regardless of whether you are setting device-control parameters or requesting 
information, you always use a record of type Detype. The structure of Detype 
is: 

Detype = RECORD 

deversion: INTEGER; 

decode: INTEGER; 

dcData: ARRAY[0..9] OF LONGINT 

END; 

dcVersion: currently 2 

decode: control code for device driver 

dcData: specific control or data parameters 


2.10.12.1 Setting Device-Control Information 

Before you use a device, you call DEVlCEjCONTROL to set the device driver. 
Once you begin using the device, you call DEVICE CONTROL as necessary. 

Table 2-1 shows which groups of device-control functions must be set before 
using each type of device. Table 2-2 shows which characteristics are 
contained in each group. For example, you must set Group A for RS-232 
input. As you see in Table 2-2, Group A indicates the type of parity used 
with the device. Each group requires a separate call to DEVICE_CCNTROL, 
and you can set only one characteristic from each group. If you set more 
than one from the same group for a particular device, the last one set will 
apply. 
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Table 2-1 

DEVICE CONTROL Functions Required 
before Using a Device 


Device Type 

Device Name Required Groups 

Serial RS-232 for 
input 

RS232A or RS232B 

A, C y D y E y F, G 

Serial RS-232 for 
output or printer 

RS232A or RS232B 

A, B, C, G, H, I 

ProFile 

SLOTxCHANy (where 
x and y are numbers) 
or PARAPORT 

J 

Parallel printer 

SLOTxCHANy (where 
x and y are numbers) 
or PARAPORT 

I 

Console screen and 
keyboard 

MAINC0NS0LE or 
ALTC0NS0LE 

I 

Diskette drive 

UPPER or LOWER 

J 


Here is a sample program that shows how a device-control parameter is set. 
This program sets the parity attribute for the RS232B port to "no parity." 
Note that the parity attribute requires only that you set cparm.dccode and 
cparm.dcdata(0]. Other parameters require that you also set cparm.dcdata[l] 
and cparm.dcdata[2l They are set in a similar manner. 

VAR 

cparm: dctype; 
errnum: integer- 
path: pathname; 

BEGIN 

path:='-RS232B‘; 

cparm.deversion:=2; (* always set this value *) 

cparm.decode:= 1; 

cparm.dcdata[0]:= 0; 

DEVICE_CONTROL(ermunt path, cparm); 

END; 
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Table 2-2 shows how to set cparmdccode, cpaim.dcdata(0], cpaimdcdataflj, 
and cparmdcdata[2] for the various available attributes. Note that any values 
in cparradcdata past cpanadcdata[2] are ignored when you are setting 
attributes documented here. 


Table 2-2 

DEV ICECONTROL Output Functional Groups 


FUNCTION _ .decode .dedatafol .dcdatafll ,dcdataf2l 


Group A—Parity: 

No parity 1 

Odd parity, no 1 

input parity 
checking 

Odd parity, 1 

input parity 
errors = 00 

Even parity, no 1 

input parity 
checking 

Even parity, 1 

input parity 
errors = $80 


0 

1 

2 

3 

4 


Group B—Output Handshake: 
None 11 

DTR handshake 2 

xon/xoff handshake 3 

delay after Cr, LF 4 


ms delay 


Group C--Baud rate: 


5 


baud 


Group D—input waiting during ReadData: 
wait for Count bytes 6 0 

return whatever rec'd 6 1 

Group E—Input handshake: 

no handshake 7 

9 -1 

DTR handshake 7 

XON/XOFF handshake 8 


-l 


32767 
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Table 2-2 (continued) 


FUNCTION 

.decode .dedatafol 

.dcdatafll 

.dcdataf2l 

Group F—Input typeahead buffer: 



flush only 

9 -1 

-2 

-2 

flush and re-slze 

9 bytes 

-2 

-2 

flush, re-size. 

9 bytes 

low 

hi 

and set threshold 




Group G—Disconnect Detection: 



none 

10 0 

0 

-- 

BREAK detected 

10 0 

non-zero 

— 

means disconnect 




Group H—Timeout on output (handshake Interval): 


no timeout 

12 0 

— 

-- 

timeout enabled 

12 seconds 

— 

— 

Group I—Automatic linefeed insertion: 



disabled 

17 0 

— 

— 

enabled 

17 1 

— 

— 

Group J—Disk errors 

(set to l to enable. 

to 0 to disable): 

enable sparing 

21 sparing 

rewrite 

reread 

Group K—Break command (never required — 

available only on serial 


RS-232 devices): 



send break 

13 millisecond 0 

-- 


duration 



send break 

13 millisecond 1 

-- 

while lowering DTR duration 




Using Group C, you can set baud to any standard rate. However, 3600, 7200, 
and 19200 baud are available only on the RS232B port. 

"Low" and “Hi" under Group F set the low and high threshold in the typeahead 
input buffer. When "Hi" or more bytes are in the input buffer, X0FF is sent 
or DTR is dropped. When “Low" or fewer bytes are in the typeahead buffer, 
X0N is sent or DTR is reasserted. The size of the typeahead buffer (bytes) can 
be any value between 0 and 102a bytes inclusive. 

In Group J, enabling disk sparing permits the device driver to relocate blocks 
of data from areas of the disk that are found to be bad. Enabling disk rewrite 
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permits the operating System to rewrite data that It had trouble reading. Out 
finally managed to read. This condition is referred to as a soft error. 

Enabling disk reread tells the Operating system to read data after they are 
written to make certain that they were written correctly. 

When sending a break command, as shown In Group K, any device control from 
Group A removes the break condition even if the allotted time has not yet 
elapsed. Also, sending a break will disrupt transmission of any other character 
still being sent. If you want to make certain that enough time has elapsed for 
the last character to be transmitted, call WR1TE_DATA with a single null 
character (equal to 0) just prior to calling DEVICE_CCNTR0L to send the break. 

Table 2-3 gives a list of mnemonic constants that you can use In place of 
explicit numbers when setting Decode. These mnemonics are provided for 
convenience. 

Table 2-3 
Decode Mnemonics 


Decode 

Mnemonic 

1 

dvParity 

2 

dvQUtDTR 

3 

dvOutXQN 

4 

dvOutDelay 

5 

dvBaud 

6 

dvInWait 

7 

dvInDTR 

8 

dvInXON 

9 

dvTypeahd 

10 

dvDiscon 

11 

dvOutNoHS 

12 

no mnemonic 

13 

no mnemonic 

15 

dvErrStat 

16 

dvGetEvent 

17 

dvAutoLF 

20 

dvDiskStat 

21 

dvDiskSpare 


2.10.12.2 Obtaining Device-Control information 

To use DEV1CE CONTRCL to find out about the current state of a particular 
device, simply give the pathname for the particular device along with a 
function code for the type of information you need. The record of type Detype 
that you supply Is returned filled with information. 
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There are three types of Information requests you can make. Note that each 
type applies only to some of the available devices. The request types and the 
returned Information are described In Table 2-4. 

Table 2-5 shows the error code provided In response to a Decode- 15 
Information request This code Is given in cparm.dcdata(l]], The code, a long 
Integer, Is shown In Table 2-5; the bits and bytes are numbered from the right, 
counting from 0, as shown In Figure 2-1. The meaning assigned to the bit 
applies if the bit Is set (equals l). 



Figure 2-1 

Disk Hard Error Codes 


Here Is a program fragment that uses DEVICE CONTROL to get information 
about the upper diskette drive. 

VAR 

epar*: detype; 
ermum: INTEGER; 
path: pathrane; 

BEGIN 

path:=‘-UPPER*; 

epaorm.deversion:-2; (* always set this value *) 

epans.decode := 20; 

DEVICE CONTROL (ermine path, epar*); 
flTH epara DO 

•RITELN (dcdata[0Ldcdata[l],dcdata[2],dcdata[3], 
dcdata[4 j, dcdata[51 dcdata[6 ]) 

END; 
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Table 2-4 
Device Information 


Decode Devices_Returned In DcQata 


15 ProFiles [0] contains disk error status on 

last hardware error (see Table 
2-5) 

[1] contains error retry count 
since last system boot 

16 Console Screen [0] contains numbers 0-10, 

and Keyboard which indicate events: 

0 = no event 

1 = upper diskette inserted 

2 = upper diskette button 

3 = lower diskette Inserted 

4 = lower diskette button 

6 = mouse button down 

7 = mouse plugged in 

8 = power button 

9 = mouse button up 
10 = mouse unplugged 

[1] contains the current state of 
certain keys. Indicated by set 
bits (if the bit is 1, the key is 
pressed) (bits are numbered from 
the right) 

0 = caps lock key 

1 = shift key 

2 = option key 

3 = command key 

4 = mouse button 

5 = auto repeat 

[2] contains X and Y coordinates 
of mouse, X in left 2 bytes, Y in 
right 2 bytes 

[3] contains timer value in 
milliseconds 
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Table 2-4 (continued) 

Decode Devices _ Returned In Dedata _ 

20 ProFile or [0] contains: 

Diskette Drive 0 = no disk present 

1 = disk present (but not 

accessed yet) 

The following indicate that a 
disk Is present and has been 
accessed at least once. 

2 = bad block track appears 

unformatted 

3 = disk formatted by some 

program other than the 
Operating System 

4 = OS-formatted disk 

[1] contains: 

0 = no button press pending 
1 = button press pending, 
disk not yet ejected 

[2] contains number of available 
spare blocks, 0-16, 
meaningful only when 
Dcdatafo] = 4 and for a 
diskette 

[3] contains: 

0 = both copies of the 
bad-block directory OK 
1 = one copy is corrupt 
(meaningful only when 
Dcdata[0] = 4) 

[4] contains: 

0 = sparing disabled 
1 * sparing enabled 

[5] contains: 

0 = rewrite disabled 
1 = rewrite enabled 

[6] contains: 

0 = reread disabled 
1 = reread enabled 
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Table 2-5 

Disk Hard Error Codes 


Byte 3 

7 = Profile received <> 55 to its last response 

6 = Write or write/verify aborted because more than 532 bytes of 

data were sent or because ProFile could not read its spare 
table 

5 = Host's data is no longer in RAH because ProFile updated its 

spare table 

4 = SEEK ERROR — unable in 3 tries to read 3 consecutive headers 

on a track 

3 = CRC error (only set during actual read or verify of 

write/verify, not while trying to read headers after seeking) 

2 = TIHEOUT ERROR (could not find header in 9 revolutions)— not 

set while trying to read headers after seeking 

1 = Not used 

0 = Operation unsuccessful 
Byte 2 

7 = seek ERROR — unable in l try to read 3 consecutive headers 

on a track 

6 = spared sector table overflow (more than 32 sectors spared) 

5 - Not used 

4 = Bad block table overflow (more than loo bad blocks in table) 

3 - ProFile unable to read its status sector 

2 = sparing occurred 

1 = Seek to wrong track occurred 
0 * Not used 

Byte l 

7 = ProFile has been reset 

6 = invalid block number 

5 = Not used 

4 = Not used 

3 = Not used 

2 = Not used 
l = Not used 
0 = Not used 

Byte 0 

This byte contains the number of errors encountered when rereading a 
block after any read error. 
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2.10.13 ALLOCATE File System call 

ALLOCATE (Var Ecode:Integer; 

RefNui: Integer- 
Contiguous : Boolean; 

Count:Longlnt; 

Var Actual:Integer) 

Ecode: Error indicator 

RefNun: Reference number of object to De allocated space 

Contiguous: True = allocate contiguously 
Count: Number of blocks to be allocated 

Actual: Number of blocks actually allocated 

Use ALLOCATE to Increase the space allocated to an object if possible, 
ALLOCATE adds the requested number of blocks to the space available to the 
object referenced by RefNum. The actual number of blocks allocated Is 
returned in Actual, if contiguous is true, the new space is allocated in a 
single, unfragmented space cm the disk. This space is not necessarily adjacent 
to any existing file blocks. 

ALLOCATE applies only to objects on block-structured devices. An attempt to 
allocate more space to a pipe is successful only if the pipe's read pointer is 
less than or equal to its write pointer. If the write pointer has wrapped 
around but the read pointer has not, an allocation would cause the reader to 
read invalid and uninitialized data, so the File System returns error 1186 in 
this case. 
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2.10.14 COMPACT File System Call 

COMPACT (Var Erode:Integer; 

RefNum:Integer) 

Ecode: Error Indicator 

RefNum: Reference number of object to be compacted 

COMPACT changes the Physical End of File to deallocate any blocks after the 
block that contains the Lexical End of File for the file referenced by RefNum 
(See Figure 2-1.) COFACT applies only to objects on block-structured 
devices. As In the case of ALLOCATE, compaction of a pipe Is legal only If 
the read pointer Is less than or equal to the write pointer. If the write pointer 
has wrapped around, but the read pointer has not, compaction could destroy 
data in the pipe. The File System returns error 1188 In this case. 
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2.10.15 TRUNCATE File system call 

TRUNCATE (War Ecode:Integer; 

RefNum:integer) 

Ecode: Error indicator 

RefNum: Reference number of object to be truncated 

TRUNCATE sets the Logical End of File Indicator to the current position of 
the file marker. Any data beyond the file marker are lost TRUNCATE 
applies only to block-structured devices. Truncation of a pipe can destroy 
data that have been written but not yet read. As the diagram shows, 
TRUNCATE changes only LEOF. COMPACT, on the other hand, changes only 
PEOF. 



Figure 2- 2 

The Relationship of COMPACT and TRUNCATE 

In this figure the boxes represent blocks of data Note that LEOF can point to 
any byte In the file but PEOF always points to a block boundary. Therefore, 
TRUNCATE can reset LEOF to any byte In the file, but COMPACT can reset 
PEOF only to a block boundary. 
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2.10.16 flush File System Call 

FLUSH (Var Ecode:Integer; 

Rem*: Integer) 

Ecode: Error Indicator 

RefNum: Reference number of destination of I/O 

FLUSH forces all buffered Information destined for the object Identified by 
RefNum to be written out to that object 

A side effect of FLUSH Is that all FS buffers and data structures are flushed 
(as well as the control Information for the referenced file). If RefNum Is -l, 
only the global File System Is flushed. This Is a method by which an 
application can ensure that the File System Is consistent 
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Z.1Q.17 SETSAFETY File System Call 

SETSAFETY (var Ecode: Integer; 

Var Path:Pathname; 

On_off:Boolean) 

Ecode: Error indicator 

Path: Name of object containing safety switch 

OnOff: Set safety switch: 

On » true 
Off » false 


Each object in the File System has a "safety switch" to help prevent accidental 
deietlo a If the safety switch is on, the object cannot be deleted. 

SET SAFETY turns the switch on or off for the object identified by path. 
Processes that are sharing an object should cooperate with each other when 
setting or clearing the safety switch. 
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2.10.18 SETWCRKINGDIR and QET_WORKINQ_DIR File System Calls 

SET_WORKING_DIR (Var Ecode:Integer; 

Var Path:Pathname) 

GETWORKINGDIR (Var Ecode .-integer; 

Var Path:Pathname) 

Ecode: Error Indicator 

Path: working directory name 

The Operating System uses the working directory name to resolve partially 
specified pathnames Into complete pathnames. GETWCRKINGDIR returns the 
current working directory name In Path. SET WCRKING DIR sets the working 
directory name. 

The following program fragment reports the current name of the working 
directory and allows you to set it to something else: 

VAR Work IngDlr:PathName; 

ErrorCOde:INTEGER; 

BEGIN 

GET_NORKlNG_DiR(ErrorCode, WorkingDir); 

IF (Errorcode<>0) THEN 

•RITELNCCannot get the current working directory!') 

ELSE VRITELN('The current working directory is: WorkingDir); 
WRITE('New working directory name: '); 

READLN(WorkingDir); 

SET_WORKlNG_DlR(ErrorCode, WorkingDir); 

END; 
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2.10.19 RESETCATALOG and GET NEXT ENTRY File System Calls 

RESETCATALOG (Var Ecode:INTEGER; 

Var Path:Pathname) 

GET NEXT ENTRY (Var Ecode:INTEGER; 

var Prefix, 

Entry:E_Name) 

Ecode: Error indicator 

Path: Working directory name 

Prefix: Beginning of file names returned 

Entry: Names from catalog 

RESETCATALOG and GET NEXT ENTRY give a process access to catalogs. 
RESETjCATALOG sets the catalog file marker to the beginning of the catalog 
specified by Path. Path should be a root volume name. G£T_NEXT_ENTRY 
then performs sequential reads through the catalog file specified In the 
RESETjCATALOG call and returns File System object names. An end-of-flle 
error code (848) Is returned when GETNE XTENTRY reaches the end of the 
catalog, if Prefix Is non-null, only those entries In the catalog that begin with 
that prefix are returned. If Prefix Is ”AB", for example, only file names that 
begin with ”AB" are returned. The prefix and catalog marker are local to the 
calling process, so several processes can simultaneously read a catalog without 
affecting each other. 
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2.1020 MOUNT and unmount File System Calls 

MOUNT (var Ecode:integer; 

Var VNa«e:E_Name; 

Var Password:E_Name 
Var Devname :E_Name) 

UNMOUNT (Var Ecode:Integer; 

Var Vname:E_nane) 

Ecode: Error indicator 

Vname: Volume name 

Password: Password for device (currently ignored) 

Devname: Device name 

MOUNT and UNMOUNT handle access to sequential devices or block-structured 
devices. For block-structured devices, MOUNT logically attaches the volume's 
catalog to the File System. The name of the volume mounted Is returned In 
the vname parameter. 

UNMOUNT detaches the specified volume from the File System. No object on 
that volume can be opened after UNMOUNT has been called. The volume 
cannot be unmounted until all the objects on the volume have been closed by 
all processes using them. 

Devname is the name of the device on which a volume Is being mounted. 
Devname should be given without a leading dash (-). 

vname Is the name of the volume that was successfully mounted, and Is 
returned. 


2-40 



Chapter 3 
Processes 

5.1 Process Structure.3-2 

3 2 Process Hierarchy.3-2 

33 Process Creation.3-3 

3.4 Process Control.3-3 

3.5 Process Scheduling.3-3 

3 .6 Process Termination.3-4 

3.7 A Process-Handling Example.3-5 

3.8 Process System Calls.3-7 

3.8.1 MAKE_PROCESS.3-8 

3.8.2 TERMINATE_PROCESS.3-9 

3.83 1NF0_PR0CESS.3-11 

3.8.4 KILL.PROCESS.3-13 

3.8.5 SUSPEND_PROCESS.3-14 

3.8.6 ACTIVATE_PROCESS.3-15 

3.8.7 SETPRICRITY_PROCESS.3-16 

3.8.8 YIELDCPU.3-17 

3.8.9 MY ID.3-18 





















Processes 


A process is an entity in the Lisa system that performs work. When you ask 
the Operating System to run a program, the OS creates a specific instance of 
the program and its associated data. That instance is a process. 

The Lisa can have a number of processes at any one time; they appear to be 
running simultaneously. Although processes can share code and data, each 
process has its own stack. 

Only one process at a time can use the CPU. The Scheduler determines 
which process is active at a particular time. The Scheduler allows each 
process to run until some condition that would slow execution occurs (an I/O 
request, for example). At that time, the running process is saved in its 
current state. The Scheduler then checks the pool of ready-to-run processes. 
When the original process later resumes execution, it picks up where it left 
off. 

The process scheduling state has three possibilities. A running process is 
actually executing instructions. A ready process is ready to execute but is 
being held back by the Scheduler. A blocked process is ignored by the 
Scheduler. It cannot continue its execution until something causes it to 
become ready. Processes commonly become blocked while awaiting 
completion of I/O, although there are a number of other likely causes. 
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3.1 Process Structure 

A process can use up to 16 data segments and 106 code segments. 

The layout of the process address space for user processes Is shown In Figure 
3-1. 

Seg# 

--------- 

0 | unavailable 

- 

1 | User Code Segments 


106 | 

+-- 

107 | LDSN 1 

. I 

| (data segments) 


122 

123 

«—« 

124 
+ -■ 

125 
*-■ 

126 
127 


LDSN 16 
Stack 

Shared Intrinsic Unit Data 

Screen 

Reserved 

Reserved 


Figure 3-1 

Process Address Space Layout 

Each process has an associated priority, an integer between 1 and 255. The 
Scheduler usually executes the highest-prlority ready process. The higher 
priorities (226 to 255) are reserved for the Operating System. 

3 2 Process Hierarchy 

When the system is first started, several system processes exist At the base 
of the process hierarchy, shown in Figure 3-2. is the root process, which 
handles various internal Operating System functions. It has at least two sons: 
the Memory Manager process and the shell process. 

The Memory Manager process handles code and data segment swapping. 
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The shell process Is a user process that is automatically started when the OS 
Is Initialized. It Is typically a command Interpreter, but It can be any 
program. The OS simply looks for the program called SYSTEM.SHELL aid 
executes it. 


Root Process 



Other User Processes 

Figure 3-2 
Process Tree 

Any other system process (the network control process, for example) is a son 
of the root process. 

3.3 Process Creation 

When a process is created, it is placed in the ready state with a priority equal 
to that of the process that created it. All the processes created by a given 
process can be thought of as existing in a subtree. Many of the process 
management calls affect the entire subtree of a process as well as the process 
itself. 

3.4 Process Control 

Three system calls are provided for explicit control of a process. These calls 
allow a process to kill, suspend (block), or activate any other user process in 
the system, as long as the process identifier is known. Process-handling calls 
are not allowed to control Operating System processes. 

3.5 Process Scheduling 

Process scheduling is based on the priority established for the process and on 
requests for Operating System services. 

The Scheduler generally executes the highest-prlorlty ready process. Once a 
process is executing, it loses the CPU only under certain circumstances. The 
CPU is lost when there is some specific request for the process to wait (for 
an event, for example), when there is an I/O request, or when there is a 
reference to a code segment that is not in memory. A process that makes 
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any Operating system call may lose tne CPU. me process gets tne CPU Pack 
when the Operating System is finished, except under the following conditions: 

• The running process requests input or output. The Scheduler starts the 
next highest-priority process running while the first process waits for the 
I/O to complete. 

• The running process lowers its priority Delow that of another ready process 
or sets another process's priority higher than its own. 

• The running process explicitly yields the CPU to another process. 

• The running process activates a higher-priority process. 

• The running process suspends itself. 

• A higher-priority process becomes ready. 

• The running process needs code to be swapped into memory. 

• The running process executes an event-wait call. 

• The running process calls DELAY_TIME. 

Because the Operating System cannot seize the CPU from an executing 
process except in the cases noted above, background processes should be 
liberally sprinkled with YIELD_CPU calls. 

When the Scheduler is invoked, it saves the state of the current process and 
selects the next process to run by examining the pool of ready processes. If 
the new process requires that code or data be loaded into memory, the 
Memory Manager process is launched. If the Memory Manager is already 
working on a process, the Scheduler selects the highest priority process in the 
ready queue that does not need anything swapped. 

3.6 Process Termination 

A process terminates under one of the following conditions: 

• It calls TERM1NATE_PR0CESS. 

• It reaches an ’END.' statement 

• It is referred to in a kill_PROCESS call. 

• Its father process terminates. 

• It runs into an abnormal condition. 

When a process begins to terminate, a SYS_TERMINATE exception condition is 
signaled to the terminating process and all of the processes it has created. 

By means of the DECLARE JiXCEPJHDL call (described in Chapter 5), any 
process can create an exception handler to catch the terminate exception and 
clean up before terminating. The SYS_TERM1NATE exception handler will be 
executed only once, if an error occurs while the handler is executing, the 
process terminates immediately. 
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A process can call K1LL_PR0CESS on any user process whose Procjd Is 
known. TERMINATEPROCESS, on the other hand, terminates the process that 
called It (and its descendants). TERM1NATE_PR0CESS also allows an event to 
be sent to the father of the terminating process if a local event channel was 
specified in the make_process call. 

Termination Involves the following steps: 

1. Signal the SYS_TERM1NATE exception on the terminating process. 

2. Execute the user's exception handler, if any. 

3. instruct all sons of the current process to terminate. 

4. Close all open files, data segments,pipes, and event channels left open by 
the user process. 

5. Send the SYS_SON_TERM event to the father of the terminating process 
If a local event channel exists. 

6. Walt for all the sons to finish termination. 

3.7 A Process-Handling Example 

The following programs illustrate the use of many of the process-management 
calls described in this chapter. The program Father, below, creates a son 
process and lets it run for a while. It then gives the user a chance to 
activate, suspend, kill, or get information about the son. 

PROGRAM Father; 

USES (*$U Source:SysCall.Obj") SysCall; 

VAR ErrorCode:INTEGER; ("error returns from system calls *) 
procld:LONGINT; (* process global identifier *) 

progname:Pathname; (* program file to execute *) 

null.-NameString; (* program entry point *) 

Info_RecProclnfoRec; (* information about process «) 
i: INTEGER; 

Answer: CHAR; 
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BEGIN 

ProgNarae:='SON.OBJ’; (* this program is defined below*) 
Null:=''; 

MAKEPROCESS (ErrorCode, Procld, ProgName, Null, 0); 

IF (ErrorcodeoO) THEN 

•RITELNCError ',ErrorCode,* during process management.'); 
FOR i:=l TO 15 DO (* idle for awhile *) 

BEGIN 

iRITELNCFather executes for a moment.'); 
YIELO_CPU(ErrorCode,FALSE); (* let son run *) 

END; 

•RITE('K(ill S(uspend A(ctivate I(nfo'); 

REA0LN( Answer); 

QASEi Ansvsr OF 

'K', 'k': KILL_PROCESS(ErrorCode,Proc_Id); 

'S','s': SUSPEND_PROCESS(ErrorCode,Proc_Id,TRUE (* suspend 

family *)); 

'A','a': ACTIVATE_PROCESS(ErrorCode,Proc_Id,TRUE (* activate 

family *)); 

'I', 'i': BEGIN 

INFO_PROCESS(ErrorCode, Procld, Info_Rec); 

WRITELNCSon' 's name is ',Info_Rec.ProgPathName); 

END; 

END" 

IF (ErrorcodeoO) THEN 

KRITELN('Error *,ErrorCode,' during process management.’); 

END. 

The program Son is: 

PROGRAM Son; 

USES (*$U Source:SysCall. Ob j*) SysCall; 

VAR ErrorCode:INTEGER; 

null:NameString; 

BEGIN 

WHILE TRUE DO 
BEGIN 

WRITELN('Son executes for a moment.'); 

YlELDjDPU(ErrorCode,FALSE);(*let father process run*) 

END; 

END. 
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3.8 Process System Calls 

This section describes the Operating System calls that pertain to process 
control. A summary of all the Operating System calls can be found In 
Appendix A. The following special types are used In process-control calls: 

Pathname = STRING[255]; 

Naraestring = STRING[20]; 

Pseventblock = *s_eventblock; 

S_eventblock = T_event_text; 

T_event_text = array [0. .sizeetext] of longint; 

ProcInfoRec = record 

progpathname : pathname; 

global_id : longint; 

father_id : longint; 

priority : 1..255; 

state : (pactive, psuspended, pvaiting); 

data in : boolean 

end; 
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3.8.1 MAKE_PROCESS Process System Call 

MAKE_PROCESS (Var ErrNum:Integer; 

Var ProcIdrLonglnt; 

Var ProgFile:Pathname; 

Var EntryName:NameString; (* NameString = STRING[20] ») 
Evnt_Chn_RefNum:Integer) 


ErrNum: 

Proc_Id: 

ProgFile: 

EntryName: 

Evnt Chn RefNum: 


Error indicator 

Process identifier (globally unique) 
Process file name 
Program entry point 
Communication channel between calling 
process and created process 


A son process is created when another process, the father process, calls 
MAKEPROCESS. The son process executes the program identified by the 
pathname in ProgFile. If ProgFile is a null character string, the program name 
of the father process is used. A globally unique identifier for the son process 
is returned in Proc_Id. 

Evnt_Chn_RefNum is a local event channel supplied by the father process. 
Event channels are discussed in Chapter 5. The Operating System uses the 
event channel identified by Evnt_Chn_RefNum to send trie father process 
events regarding the son process (for example, SYS_SON_TERM). if 
Evnt_Chn_RefNum is zero, the father process is not informed when such 
events are produced. 

EntryName, if non-null, specifies the program entry point where execution is 
to begin. Because alternate entry points have not yet been defined for 
Pascal, this parameter is currently ignored. 

Any error encountered during process creation is reported in ErrNum. 
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3 . 8.2 terminate_process Process System call 

TERHlNATE_PROCESS(Var ErrNum integer; 

EventPtr; Pseventblk) 

ErrNum: Error indicator 

Event_Ptr: Information sent to process's creator 

A process can be ended by TERM1NATE_PR0CESS. This call causes a 
SYS_TERMINATE exception to be signaled for the calling process and for all 
of the processes it has created. The process can declare its own 
SYS_TERMINATE exception handler to handle whatever cleanup it needs to do 
before it is actually terminated by the system. When the terminate exception 
handler is entered, the exception information block contains a longint that 
describes the cause of the process termination: 

Excep_Data[0] - 0 Process called TERMINATEPROCESS. 

1 Process executed the 'end.' statement. 

2 Process called KILL_PROCESS on itself. 

3 Some other process called K1LL_PR0CESS on the 
terminating process. 

4 Father process is terminating. 

5 Process made an invalid system call (that is, an 
unknown call). 

6 Process made a system call with an invalid ErrNum 
parameter address. 

7 Process aborted due to an error while trying to swap 
in a code or data segment 

8 Process exceeded its maximum specified stack size. 

9 Process aborted due to possible lockup of the system 
by a data space exceeding physical memory size. 

10 Process aborted due to a parity error. 

There are an additional twenty-six errors that can be signaled. The entire list 
is shown at the beginning of Appendix A. 

If the terminating process was created with a communication channel, a 
SYS_SON_TERM event is sent to the terminating process's father. The 
terminating process can specify the text of the SYS_SON_TERM with the 
Event_Ptr parameter. Note that the first (O'th) longint of the event text is 
reserved by the system. When the event is sent to the father, the OS places 
the termination cause of the son process in the first longint. This is the same 
termination cause that was supplied to the terminating process itself in the 
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SYS_TERMINATE exception information block. Any user-supplied data in the 
first longint of the event text is overwrittea 

If a process specifies an event to be sent in the TERMINATEPROCESS call 
but the process was created without a local event channel, no event is sent to 
the father. 

If the process was created with a local event channel, an event is sent to the 
father if the process calls TERMINATE PROCESS with a nil Event_Ptr or if 
the process terminates by a means other than calling TERM1NATE_PR0CESS. 
The event contains the termination cause in the first longint and zeroes in the 
remaining event text 

Pseventblk is a pointer to seventblk, defined as: 

CONST sizeetext = 9; (* event text size - 40 bytes *) 

TYPE t_event_text = ARRAY [0..slze_etext] OF Longint; 
seventblk = teventtext; 

If a process calls TERMINATE PROCESS twice, the Operating System forces it 
to terminate even if it has disabled the terminate exception. 
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3.8.3 INFOPROCESS Process System Call 

INFOPROCESS (Var ErrNum: Integer; 

ProcId:LongInt; 

Var ProcJnfo:ProcInfoRec); 

ErrNum: Error indicator 

Proc_Id: Global identifier of process 

Proc_Info: Information about the process Identified Oy 

Proc_Id 

A process can call INFO_PROCESS to get a variety of information about any 
process Known to the Operating System. Use the function MY_ID to get the 
Procjd of the calling process. 

ProcInfoRec is defined as: 

TYPE ProcInfoRec = RECORD 
ProgPathname:Pathname; 

GloOal_id .-Longint; 

Priority -.1..2S5; 

State :(PActive,PSuspended,Piaiting); 

Datain : Boolean 

END; 

Datajn indicates whether the data space of the process is currently in 
memory. 

The procedure on the next page gets information about a process and displays 
some of it. 


3-11 




Operating System Reference Manual 


Processes 


PROCEDURE Display_Info(Proc_Id:LONGINT); 

VAR ErrorCode:INTEGER; 

Info_Rec:ProcInfoRec; 

BEGIN 

INFO_PROCESS(ErrorCode,Proc_Id,lnfo_Rec); 

IF (ErrorCode=100) THEN 

*RITELN(’Attempt to display info about nonexistent 
process.*) 

ELSE 

BEGIN 

KITH Info Rec DO 
BEGIN 

DRITELNC program name: *,ProgPathName); 
VRITELN(* global id: *,Global_id); 

HRITELN(* priority: *,priority); 

•RITEC state: *); 

CASE State OF 

PActive: VRITELN('active *); 

PSuspended: «RITELN( suspended*); 
plaiting: «RITELN(* waiting*) 

END 

END 

END 

END; 
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3.8.4 KILL PROCESS Process System Call 

KILL_PROCESS (Var ErrNum:Integer; 

Proc_ld:LongInt) 

ErrNum: Error indicator 

Proc_Id: Process to be killed 

KILL_PROCESS kills the process referred to by Proc_ld and all of the 
processes in its subtree. The actual termination of the process does not occur 
until the process is In one of the following states: 

• Executing in user mode. 

• Stopped due to a SUSPEND_PROCESS call. 

• Stopped due to a DELAY_TIME call. 

• Stopped due to a WAIT_EVENT_CHN or SEND EVENT CHN call, or 
READ_DATA or WRITE_DATA to a pipe. 
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3.8.5 SUSPEND_PROCESS Process System Call 

SUSPENDPROCESS (Var ErrNum:Integer; 

Proc_Id:LongInt; 

Susp_Family:Boolean) 

ErrNum: Error indicators 

Proc Id: Process to be suspended 

Susp_Famiiy: if true, suspend the entire process subtree 

SUSPEND_PROCESS allows a process to suspend (block) any process in the 
system. The actual suspension does not occur until the process referred to by 
Proc_Id is in one of the following states: 

• Executing in user mode 

• Stopped due to a DELAY_TIME call 

• Stopped due to a WAIT_EVENT_CHN call 

Neither expiration of the delay time nor receipt of the awaited event causes 
a suspended process to resume execution. SUSPENDJ^ROCESS is the only 
direct way to block a process. Processes, however, can become blocked during 
I/O, by the timer (see DELAY_TIME), or for many other reasons. 

If Susp_Family is true, the Operating System suspends both the process 
referred to by Procjd and all of its descendents. If Susp_Family is false, 
only the process identified by Procjd is suspended. 
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3.8.6 ACHVATE_PROCESS Process System Call 

ACnvATE_PROCESS(Var ErrNum:Integer; 

Proc_Id:LongInt; 

Act_Family .-Boolean) 

ErrNum: Error indicator 

Proc_Id: Process to be activated 

Act_Family: If true, activate the entire process subtree 

To awaken a suspended process, call ACTlVATE_PROCESS. A process can 
activate any other process in the system. Note that ACTIVATE_PROCESS can 
awaken only a suspended process. If the process is blocked for some other 
reason, ACTIVATEPROCESS cannot unblock it. If Act Family is true, 
ACTIVATE_PRCCESS also activates all the descendents of the process referred 
to by Procjd. 
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3.8.7 SETPRIORITY PROCESS Process System Call 

SE7PRI0RITY_PR0CESS(Var ErrNum:Integer; 

Proc_Id:Longlnt; 

NewPriority: Integer) 

ErrNum: Error indicator 

Proc_Id: Global id of process 

New_Priority: Process’s new priority number 

SETPRICRITY_PROCESS changes the scheduling priority of the process 
referred to by Procjd to New_Priority. The priority value must be between 1 
and 225. (Operating System processes execute with priorities between 226 
and 255.) The higher the priority, the more likely the process is to be allowed 
to execute. 
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3.8.8 YIELDCPU Process System Call 

YlELD_CPU(Var ErrNuro: Integer; 

To_Any:Boolean) 

ErrNum: Error indication 

To_Any: Yield to any process, or only higher or equal 
priority 

Background processes should use YIEUDCPU often to allow other processes to 
execute when they need to. Successive yields 0y processes of the same 
priority result in a "round robin” scheduling of the processes, if To Any is 
true, YIELDjCPU causes the calling process to yield the CPU to any other 
ready process. If ToAny is false, YIELD_CPU causes the calling process to 
give the CPU to any other ready-to-execute process with an equal or higher 
priority. If no process meets the To_Any criterion, the calling process simply 
continues execution. 
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3.8.9 myjd Process system Call 
MY_ID:Longint 

MY_ID is a function that returns the unique global identifier (a longint) of the 
calling process. A process can use MYJD to perform process handling calls 
on itself. 

For example: 

SetPriority_Process(ErrNunt Myjd, 100) 
sets the priority of the calling process to 100. 
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Memory Management 


Every process has a set of code segments and data segments which are in 
physical memory when they are used. The logical address used by the process 
must be translated into the physical address used by the memory controller. 
This function is handled by the memory management unit (MMU). 

4.1 Data segments 

Each process has a data segment that the Operating System automatically 
allocates to it for use as a stack. The stack segment's internal structures are 
managed by the hardware and the Operating System. 

A process can acquire additional data segments for uses such as heaps and 
interprocess communication. These additional data segments can be private 
(or local ) data segments or shared data segments. Private data segments 
can be accessed only by the creating process. When the process terminates, 
any private data segments still in existence are destroyed. Shared data 
segments can be accessed by any process that opens those segments. 

The Operating System requires that data segments be in physical memory 
before the data are referenced. The Scheduler automatically loads all of the 
data segments that the program says it needs. It is the responsibility of the 
programmer to ensure that the program declares all its needs by associating 
itself with the needed data segments before they are needed. 

This process of association is called binding. A program can bind a data 
segment to itself in several ways. When a program creates a data segment by 
using the MAKE_DATASEG call, the segment is automatically opened and 
bound to the program. If a program needs to open a segment that was 
created by another program, the OPENDATASEG call is used. That call binds 
the segment to the calling process, as well as opening the segment for the 
process. Since there may be times when a process needs to use more data 
segments than can be bound at one time, the UNBIND DATASEG call is 
provided to unbind the data segment without closing it. The program can then 
use BIND_DATASEG to bind another data segment to the program. 

The Operating System views all data segments except the stack as linear 
arrays of bytes. Therefore, allocation, access, and interpretation of structures 
within a data segment are the responsibility of the program. 

4.2 The Logical Data Segment Number 

The address space of a process allows up to 16 data segments bound to a 
process at the same time, in addition to the stack. Each bound data segment 
is associated with a specific region of the address space by means of a 
Logical Data Segment Number (LDSN). See Figure 3-1 for an illustration of 
the address space of a process. While a data segment is bound to the process, 
it is said to be a member of the working set of the process. 
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The process associates a data segment with a specific ldsn in the 
MAKEDATASEG or OPENDATASEG call. 

The LDSN, which has a valid range of 1 to 16, is local to the calling process. 
The process uses the LDSN to keep track of where a given data segment can 
be found. More than one data segment can be associated with the same LDSN, 
but only one such segment can be bound to a given LDSN at any Instant and 
thus be a member of the working set of the process. 

4.3 Shared Data Segments 

Cooperating processes can share data segments. Shared segments cannot be 
larger than 128 Kbytes in length. As with local data segments, the segment 
creator assigns the segment a File System pathname. All processes that share 
that data segment then use the same pathname. If the shared data segment 
contains address pointers to data within the segment, the cooperating 
processes must also use the same LDSN with the segment. This ensures that 
all logical data addresses referencing locations within the data segment are 
consistent for the processes sharing the segment. A shared data segment is 
permanent until explicitly killed by a process. 

4.4 Private Data Segments 

Data segments can also be private to a process. In this case, the maximum 
size of the segment can be greater than 128 Kbytes. The actual maximum 
size depends on the amount of physical memory in the machine and the 
number of adjacent LDSNs available to map the segment. The process gives 
the desired segment size and the base LDSN to map the segment. The 
Memory Manager then uses ascending adjacent LDSNs to map successive 128 
Kbyte chunks of the segment. The process must ensure that enough 
consecutive LDSNs are available to map the entire segment. 

Suppose a process has a data segment already bound to LDSN 2. If the 
program tries to bind a 256 Kbyte data segment to LDSN 1, the Operating 
System returns an error because the 256 Kbyte segment needs two consecutive 
free LDSNs. Instead, the program should bind the segment to LDSN 3 and the 
system automatically also uses LDSN 4. 

4.5 Code Segments 

Division of a program into multiple code segments (swapping units) is dictated 
by the programmer through commands to the Compiler and Linker. The MMU 
registers can map up to 106 code segments. 

4.6 Swapping 

When a process executes, the following segments must be in physical memory: 

• The current code segment 

• All the data segments in the process working set (the stack and all bound 
data segments) 

The Operating System ensures that this minimum set of segments is in physical 
memory before the process is allowed to execute. If the program calls a 
procedure in a segment not in memory, a segment swap-in request Is initiated. 
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In tne simplest case, tnis request only requires tne system to allocate a block 
of physical memory and to read in the segment from the disk. In a worse 
case, the request may require that other segments be swapped out first to 
free up sufficient memory. A clock algorithm is used to determine which 
segments to swap out or replace. This process is invisible to the program. 

4.7 Memory Management System Calls 

This section describes all the Operating System calls that pertain to memory 
management. A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used in memory management 
calls: 


Pathname = STRING[255]; 

Tdstype = (ds_shared. ds_private); 

DsInfoRec = Record 

mein_size: longint; 
disc_size:longint; 
nunt)_open: integer; 
LDSN:integer; 
boundF:boolean; 
presentF:boolean; 
creatorF:boolean; 
rwaccess:boolean; 
segptr:longint; 
volnamere name; 

end; 

E_name = string [32]; 
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4.7.1 MAKEJDATASEG Memory Management System Call 

MAKE_DATASEG (Var ErrNum:Integer; 

Var Segname:Pathname; 

HemSize, Disk_Size:Longlnt; 
Var RefNum:Integer; 

Var SegPtr:LongInt; 

Ldsn:Integer 
DstyperTdstype) 


ErrNum: 
Segname: 
Mem_Size: 
Disk_Size: 
RefNum: 
SegPtr 
Ldsn: 
Dstype: 


Error indicator 
Pathname of data segment 

Bytes of memory to be allocated to data segment 

Bytes on disk to be allocated for swapping segment 

Identifier for data segment 

Address of data segment 

Logical data segment number 

Type of dataseg (shared or private) 


MAKEDATASEG creates the data segment identified by the pathname, 
Segname, and opens it for immediate read-write access. Segname is a File 
System pathname. 

The parameter Mem_Slze determines how many bytes of main memory are 
allocated to the segment. The actual allocation takes place in terms of 
512-byte pages. If the data segment is private (Dstype is ds_prlvate), 
Mem_Size can be greater than 128 Kbytes, but you must ensure that enough 
consecutive LDSNs are free to map the entire segment. 

Disk_Slze determines the number of bytes of swapping space to be allocated 
to the segment on disk, if Disk_size is less than Mem_Size, the segment 
cannot be swapped out of main memory. In this case the segment is memory 
resident until it is killed or until its size in memory becomes less than or 
equal to its Disk_size (see SIZE_DATASEG). The application programmer 
should be aware of the serious performance implications of forcing a segment 
to be memory resident. Because the segment cannot be swapped out, a new 
process may not be able to get all of its working set into memory. To avoid 
thrashing, each application should ensure that all of its data segments are 
swappable before it relinquishes the attention of the processor. 

The calling process associates a Logical Data Segment Number (LDSN) with 
the data segment. If this LDSN is bound to another data segment at the time 
of the call, the call returns an error. 

RefNum is returned by the system to be used in any further references to the 
data segment. The Operating System also returns SegPtr, an address pointer to 
be used to reference the contents of the segment. SegPtr points to the base 
of the data segment. 

Any error conditions are returned in ErrNum. 
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wnen a data segment is created, it immediately Becomes a member of tne 
working set of the calling process. You can use UNBIND_DATASEG to free 
the LDSN. 
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1 . 7.2 KILLJDATASEG Memory Management System Call 

KILLJJATASEG (Var ErrNum:Integer; 

Var Segname-.Pathname) 

ErrNum: Error indicator 

Segname: Name of data segment to be deleted 

When a process Is finished with a shared data segment, it can issue a 
KILLJOATASEG call for that segment. (KILL DATASEG cannot be used on a 
private data segment.) If any process, including the calling process, still has 
the data segment open, the actual deallocation of the segment is delayed until 
all processes have closed it (see CL05E_D AT ASEG). During the interim period, 
however, after a KILLJDATASEG call has been issued but before the segment 
is actually deallocated, no other process can open that segment. 

KILLJDATASEG does not affect the membership of the data segment in the 
working set of the process. The RefNum and SegPtr values are valid until a 
CLOSEJOATASEG call is issued. 

One important note: normally, when a data segment is closed, the contents 
are written to disk as a file with the pathname associated with the data 
segment. If, however, the program calls KILLJDATASEG on the data segment 
before closing it, the contents of the data segment are not written to disk and 
are lost when the segment is closed. 
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4.7.3 OPEN_DATASEG Memory Management System Call 

OPEN DATASEG (Var ErrNum:Integer; 

Var Segname:Pathname; 

Var RefNum:Integer; 

Var SegPtr:Longlnt; 

Ldsn:Integer) 

ErrNum: Error indicator 

Segname: Name of data segment to De opened 
RefNum: Identifier for data segment 

SegPtr Pointer to contents of data segment 
Ldsn: Logical data segment number 

A process can open an existing shared data segment with OPENDATASEG. 
The calling process must supply the name of the data segment (Segname) and 
the Logical Data Segment Number to be associated with it. The LDSN given 
must not have a data segment currently bound to it. The segment's name is 
determined by the process that creates the data segment; it cannot be null. 

The Operating System returns both RefNum, an identifier for the calling 
process to use in future references to the data segment, and SegPtr, an 
address pointer used to reference the contents of the segment. 

When a data segment is opened, it immediately becomes a member of the 
working set of the calling process. The access mode of the newly opened 
segment is Readonly. You can use SETACCESSDATASEG to change the 
access rights to Readwrite. You can use UNBIND _DATASEG to free the 
LDSN. 

You cannot use OPEN on a private data segment, since calling CLOSE on a 
private data segment deletes it. 
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4.7.4 CLOSE_DATASEG Memory Management System Call 

CLOSEJJATASEG (Var ErrNuminteger; 

RefNum:Integer) 

ErrNum: Error indicator 
RefNum: Data segment identifier 

CLOSE_DATASEG terminates any use of RefNum for data segment operations. 
If the data segment is hound to a Logical Data Segment Number, 

CLOSE_dataseg frees that LDSN. The data segment is removed from the 
working set of the calling process. RefNum is made invalid. Any references 
to the data segment using the original SegPtr will have unpredictable results. 

If RefNum refers to a private data segment, CLOSE_DATASEG also kills the 
data segment, deallocating the memory and disk space used for the data 
segment. If RefNum refers to a shared data segment, the contents of the 
data segment are written to disk as if FLUSHDATASEG had been called. (If 
K1LL_D AT ASEG is called before CLOSE_DATASEG, the contents of the data 
segment are thrown away when the last process closes the data segment.) 

The following procedure sets up a heap for LisaGraf using the memory 
management calls: 

PROCEDURE initDataSegForLisaGraf (var ErrorCode:integer); 

CONST HeapSize-16384; (* 16 KBytes for graphics heap ») 
DiSkSize=16384; 

VAR HeapBuf:L0NGINT; (* pointer to heap for LisaGraf *) 

GrafHeap:PathName; (* data segment path name *) 

Heap Refnum: INTEGER; (« refnum for heap data seg *) 

BEGIN 

GrafHeap:=‘grafheap‘; 

OPENDAT ASEG(ErrorCode, Graf Heap, Heapjtefnum, HeapBuf, 1); 

IF (ErrorCode<>0) THEN 
BEGIN 

KRITELN(‘Unable to open - ,Grafheap,‘Error is ’, ErrorCode) 
END 
ELSE 

InitHeap(POINTER(HeapBuf),POINTER(HeapBuf+HeapSize), 
aHeapError); 

END; 
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4.7.5 FLUSH_DATASEG Memory Management System call 

FLUSHDATASEG (Var ErrNum:Integer; 

RefNura:Integer) 

ErrNum: Error indicator 

RefNum: Data segment identifier 

FLUSH DATASEG writes the contents of the data segment identified by 
RefNum to the disk. (Note that CLOSEDATASEG automatically flushes the 
data segment before closing it, unless KILLJDATASEG was called first.) This 
call has no effect upon the memory residence or binding of the data segment. 
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4.7.6 SIZE_DATASEG Memory Management System Call 

SIZE_DATASEG (Var ErrNun: Integer- 
Ref nun: Integer; 
DeltaMemSize:Longlnt; 

Var NewMemSize: Longlnt; 

OeltaOiskSize:Longlnt; 

Var NewOiskSize:LongInt) 


ErrNum: 

RefNum: 

DeltaMemSize: 

NewMemSize: 

DeltaDiskSize: 

NewDiskSize: 


Error indicator 

Data segment identifier 

Amount in bytes of change in memory 

allocation 

New actual size of segment in memory 
Amount in bytes of change in disk allocation 
New actual disk (swapping) allocation 


SIZE_DATASEG changes the memory and/or disk space allocations of the data 
segment referred to by RefNum. Both DeltaMemSize and DeltaDiskSize can 
be either positive, negative, or zero. The changes to the data segment take 
place at the high end of the segment and do not destroy the contents of the 
segment, unless data are lost in shrinking the segment. Because the actual 
allocation is done in terms of pages (512-byte blocks), the NewMemSize and 
NewDiskSize returned by SIZED AT ASEG may be larger than the old size plus 
delta size of the respective areas. 

If the NewDiskSize is less than the NewMemSize, the segment cannot be 
swapped out of memory. The application programmer should be aware of the 
serious performance implications of forcing a segment to be memory resident. 
Because the segment cannot be swapped out, a new process may not be able 
to get all of its working set into memory. To avoid thrashing, each 
application should ensure that all of its data segments are swappable before it 
relinquishes the attention of the processor. 

If the necessary adjacent LDSNs are available, SIZEDATASEG can increase 
the size of a private data segment beyond 128 Kbytes. 
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47.7 INFOJDATASEG Memory Management System Call 

INFODATASEG (Var E rrNura: integer; 

RefNum:Integer; 

Var DsInfo:OsInfoRec) 

ErrNum: Error indicator 

RefNum: Identifier of data segment 

Dslnfo: Attributes of data segment 

INFOJDATASEG returns information about a data segment to the calling 
process. The structure of the DslnfoRec record is: 

RECORD 

MemSize: Longlnt (* Bytes of memory allocated to data segment »); 

Disc_Size:LongInt (* Bytes of disk space allocated to segment *); 

NuntoOpen:Integer (* Current number of processes with segment open *); 
Ldsn:Integer (* LDSN for segment binding *); 

BoundF:Boolean (* True if segment is bound to LDSN of calling proc •); 

PresentF:Boolean (* True if segment is present in memory *); 

CreatorF:Booleanm (* True if the calling process is the creator *) 

(* of the segment *); 

RWAccess:Boolean (* True if the calling process has trite access *) 
(* to segment *) 

END; 
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4.7.8 INF0_LDSN Memory Management System Call 

INFOJLDSN ( Var ErrNuro:Integer; 

Ldsn:Integer; 

Var RefNum:integer) 

ErrNum: Error indicator 

Ldsn: Logical data segment number 

RefNum: Data segment identifier 

INFO LDSN returns the refnum of the data segment currently bound to Ldsn. 
You can then use 1NFO DATASEG to get information about that data segment. 
If the LDSN specified is not currently bound to a data segment, the refnum 
returned is -1. 
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4.7.9 INFD ADORESS Memory Management system Call 

INFOADORESS (Var ErrNum: integer; 

Address:Longint; 

Var RefNuncInteger) 

ErrNum: Error indicator 

Address: The address about which the program needs information 
RefNum: Data segment identifier 

This call returns the refnum of the currently bound data segment that 
contains the address given. 

If no data segment that contains the address given Is currently bound to the 
calling process, an error indication Is returned In ErrNum. 
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4.7.10 MEMJNFO Memory Management System Call 

MEM INFO (var ErrNum:Integer; 

Var Svapspace; 

Dataspace; 

Cur_codesize; 
ttaxcodesize:Longlnt) 


ErrNum: 

Swapspace: 

Dataspace: 


Cur_codesize: 

Hax_codesize: 


Error indicator 

Amount, in bytes, of swappable system memory 

available to the calling process 

Amount, in bytes, of system memory that the 

calling process needs for its bound data areas, 

including the process stack and the shared 

intrinsic data segment 

Size, in bytes, of the calling segment 

Size, in bytes, of the largest code segment 

within the address space of the calling process 


This call retrieves information about the memory resources used by the calling 
process. 
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4 . 7.11 SETACCESSDATASEG Memory Management System Call 

SETACCESSJDATASEG (Var ErrNum: Integer- 

Ref Num: Integer ; 

Readonly:Boolean) 

ErrNum: Error indicator 

RefNum: Oata segment identifier 

Readonly: Access mode 

A process can control the kinds of access it is allowed to exercise on a data 
segment with the SETACCESS DATASEG call. Refnum is the identifier for 
the data segment, if Readonly is true, an attempt by the process to write to 
the data segment results in an address error exception condition. To get 
readwrlte access, set Readonly to false. 
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4.7.12 BIND DATASEG and UNBINDJDATASEG Memory Management System calls 

BIND_OATASEG(Var ErrNum:Integer; 

RefNum: Integer) 

UNBIND_DATASEG(Var ErrNum:Integer; 

RefNuHi: Integer) 

ErrNum: Error Indicator 
RefNum: Data segment identifier 

BIND DATASEG binds the data segment referred to by RefNum to its 
associated Logical Data Segment Numbers). UNBIND_DATASEG unbinds the 
data segment from its LDSNs. BIND_DATASEG causes the data segment to 
become a member of the current working set. At the time of the 
BIND_DATASEG call, the necessary LDSNs must not be bound to a different 
data segment. UNBIND_DATASEG frees the associated LDSNs. A reference to 
the contents of an unbound segment gives unpredictable results. 

OPEN_DATASEG and MAKEJDATASEG define which LDSNs are associated 
with a given data segment. 
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Exceptions and Events 


Processes have several ways to keep informed about the state of the system. 
Normal process-to-process communication and synchronization employ pipes, 
shared data segments, or events. Abnormal conditions. Including those your 
program may define, employ exceptions (interrupts). Exceptions are signals to 
which the process can respond in a variety of ways under your control. 

5.1 Exceptions 

Normal execution of a process can be interrupted by an exceptional condition 
(such as division by 2 ero or reference to an invalid address). Some error 
conditions are trapped by the hardware and some by the system software. The 
process itself can define and signal exceptions of your choice. 

When an exception occurs, the system first checks the state of the exception. 
The three exception states are: 

• Enabled 

• Queued 

• ignored 

If a system-defined exception is enabled the system looks for an associated 
user-defined handler. If none is found, the system invokes the default 
exception handler, which usually aborts the process that generated the 
exception. If a user-defined exception is enabled, the system invokes the 
associated user-defined exception handler. You create a new exception by 
declaring and enabling a handler for it. 

If the state of the exception is queued the exception is placed on a queue. 
When the exception is subsequently enabled, the queue is examined and the 
appropriate exception handler is invoked. Processes can flush the exception 
queue. 

If the state of the exception is ignored the system detects the occurrence of 
the exception, but the exception is neither honored nor queued. Note that 
ignoring a system-defined exception has uncertain effects. Although you can 
cause the system to ignore even the SYS_TERM1NATE exception, that 
capability is provided so that your program can clean up before terminating. 
You cannot set your program to ignore fatal errors. 

Invocation of the exception handler causes the Scheduler to run, so it is 
possible for another process to run between the signaling of the exception and 
the execution of the exception handler. 
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52 System-Defined Exceptions 

Certain exceptions are predefined by the Operating System. These include: 

• Division by zero (SYS_ZERO_DIV). The default handler aborts the process. 

• value out of bounds (that is, range check error) or illegal string index 
(SYS_VALUE_00B). The default handler aborts the process. 

• Arithmetic overflow (SYS_OVERFLOW). The default handler aborts the 
process. 

• Process termination (SYS_TERMINATE). This exception is signaled when a 
process terminates, or when there is a bus error, address error, illegal 
instruction, privilege violation, or 1111 emulator error. The default handler 
does nothing. This exception is different from the other system-defined 
exceptions in that the program always terminates as soon as the exception 
occurs, in the case of other (non-fatal) errors, the program is allowed to 
continue until the exception is enabled. 

Except where otherwise noted, these exceptions are fatal if they occur within 
Operating System code. The hardware exceptions for parity error, spurious 
interrupt, and power failure are also fatal. 

5.3 Exception Handlers 

A user-defined exception handler can be declared for a specific exception. 

This exception handler is coded as a procedure but must follow certain 
conventions. Each handler must have two input parameters: Erwironment_Ptr 
and Data_Ptr. The Operating System ensures that these pointers are valid 
when the handler is entered. Environment_Ptr points to an area in the stack 
containing the interrupted environment: register contents, condition flags, and 
program state. The handler can access this environment and can modify 
everything except the program counter, register A7, and the supervisor state 
bit in the status register. Data_Ptr points to an area in the stack containing 
Information about the specific exception. 

Each exception handler must be defined at the global level of the process, 
must return, and cannot have any EXIT or global GOTO statements. Because 
the Operating System disables the exception before calling the exception 
handler, the handler should re-enable the exception before it returns. 

if an exception handler for a given exception already exists when another 
handler is declared for that exception, the old handler becomes dissociated 
from the exception. 

An exception can occur during the execution of an exception handler. The 
state of the exception determines whether it is honored^laced on a queue, or 
ignored. If the second exception has the same name as the exception that is 
currently being handled and its state is enabled, a nested call to the exception 
handler occurs. (The system always disables the exception before calling the 
exception handler, however. Therefore, nested handler calling occurs only if 
you explicitly enable the exception.) 


5-2 



Operating System Reference Manual 


Exceptions and Events 


There is an exception-occurred flag, Ex_occurred_f, for every declared 
exception; it is set whenever the corresponding exception occurs. This flag 
can he examined and reset using the INFOJEXCEP system call. Once the flag 
is set, it remains set until FLUSH_EXCEP is called. 

The following program fragment gives an example of exception handling. 

PROCEDURE Handler (Environment_Ptnp_env_Plk; 

DataPtnpexdata); 

VAR EnNUfTtlNTEGER; 

BEGIN 

(*Environment_Ptr points to a record containing the program *) 

(•counter and all registers. Data_Ptr points to an array of 12 *) 

(•longints that contain the event header and text if this handler *) 

(*is associated with an event-call channel (See below) *) 


ENABLE_EXCEP(ermum^xcep_name); 


END; 

BEGIN («Main program*) 


Excepname.-tndOfDoc'; 

DECLARE_EXCEP_HDL(ermum^xcep_name^Handier); 


SIGNAL_EXCS^erfrnumjexcep_name^xcep_data); 


At the time the exception handler is Invoked for a SYS_TERMINATE 
exception, the stack is as shown in Figure 5-1. 
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low address 


nigh address 


Link 


Program Counter 


Data Ptr 


Environment Ptr 


Terminate Flag 


Exception Kind 
Function Code (fc) 
Access Address (aa) 
Instruction Register 
Status Register 
Program Counter 


Program Counter 
Status Register 
D0-D7 and AQ-A7 


Link 


Program Counter 


Exception Data Block 

(SYS_TERM1NATE Exception) 


Exception Environment Block 


Figure 5-1 

Stack at Exception Handler Invocation 

The Exception Data Block given here reflects the state of the stack upon a 
SYS_TERM1NATE exception. The Term_Ex_Data record (described in Appendix 
A) gives the various forms the data block can take. The Excep_Kind field (the 
first, or Oth, longint) gives the cause of the exception. The status register and 
program counter values in the data block reflect the true (current) state of 
these values. The same data in the Environment block reflects the state of 
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these values at the time the exception was signaled, not the values at the 
time the exception actually occurs. 

For SYS_ZERO_DIv, SYS_VALUE_00B / and SYS_OVERFLOW exceptions, the 
Hard_Ex_Data record descrioed in Appendix A gives the various forms that 
the data block can take. 

In the case of a Pus or address error, the PC (program counter) can he 2 to 10 
bytes beyond the current instruction. The PC and A7 cannot be modified by 
the exception handler. 

When a disabled exception is re-enabled, a queued exception may be signaled. 
In this case, the exception environment reflects the state of the system at the 
time the exception was re-enabled, not the time at which the exception 
occurred. 

5.4 Events 

An event is a piece of information sent by one process to another, generally 
to help cooperating processes synchronize their activities. An event is sent 
through a kind of pipe called an event channel. The event is a fixed-size 
data block consisting of a header and some text. The header contains control 
information, the identifier of the sending process, and the type of the event. 
The header is written by the system, not the sender, and is readable by the 
receiving process. The event text is written by the sender; Its meaning is 
defined by the sending and receiving processes. 

There are several predefined system event types. The predefined type "user" is 
assigned to all events not sent by the Operating System. 

5.5 Event Channels 

Event channels can be viewed as higher-level pipes. One important difference 
is that event channels require fixed-size data blocks, whereas pipes can 
handle an arbitrary byte stream. 

An event channel can be defined globally or locally. A global event channel 
has a globally defined pathname catalogued in the File System and can be 
used by any process. A local event channel, however, has no name and is 
known only by the Operating System and the process that opened it Local 
event channels can be opened by user processes only as receivers. A local 
channel can be opened by the father process to receive system-generated 
events pertaining to its son. 

There are two types of global and local event channels: event-wait and 
event-call. If the receiving process is not ready to receive the event, an 
event-wait type of event enamel queues an event sent to it. An event-call 
type of event channel, however, forces its event on the process, in effect 
treating the event as an exception, in that case, an exception name must be 
given when the event-call event channel is opened, and an exception handler 
for that exception must be declared, if the process reading the event-call 
channel is suspended at the time the event is sent, the event is delivered 
when the process becomes active. 
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When an event channel is created, the Operating System preallocates enough 
space to the channel for typical interprocess communication. If 
SEND_EVENT_CHN is called when the charnel does not have enough space for 
the event, the calling process is blocked until enough space is freed up. 

If WA1T EVENT CHN is called when tire channel is empty, the calling process 
is blocked until an event arrives. 

The following code fragments use event-wait channels to handle process 
synchronization, operating System calls used in these program fragments are 
documented later in this chapter. 

Process A: 


chnname := , event_chamel_l'; 

exceptions 

receiver := TRUE; 

OPEN_EVENT_CHN (errint, chn_narae, refnuml, exception, receiver); 
chn name := 'event chame 12; 
receiver := FALSE; 

OPENEVENTON (errint, chn name, refnum2, exception, receiver); 

waitlist.length := 1; 

waitlist.refnum[0] := refnuml; 

REPEAT 

eventl_ptr\[0] := aqreediponvalue; 
interval.sec := 0; (* send event immediately *) 
interval.msec := 0; 

SEND EVENT CHN (errint, refnum2, eventl_ptr, interval, elktime); 
•AIT EVENT CHN (errint, waitlist, refnum_signaling, eventZjrtr); 


(* processing performed here *) 
UNTIL AllDone; 
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Process B: 


chnname := 'event_chanrel_2'; 
exceptions "; 
receiver := TRUE; 

OPEN_EVENT_CHN (erring chnname, refnum2, exception, receiver); 
chnname := 'eventcharmeir,- 
receiver := FALSE; 

OPEN_EVENT_CHN (errint, chnname, refnuml, exception, receiver); 
waitlist.length := 1; 
waitlist.refnum[0] := refnuml; 

REPEAT 

event2_ptr*.[0] := agreedtponvalue,- 
interval.sec := 0; (* send event lmnediately ») 
interval.msec := 0; 

iAIT_EVENT_CHN (errirrt, waitlist, refnumsignaling, eventl_ptr); 


(* processing performed here *) 


SEND_EVENT_CHN (errirrt, refnum2, event2_ptr, interval, elktime); 
UNTIL AllDone; 


The order of execution of the two processes is the same regardless of the 
process priorities. Process switch always occurs at the WAIT_EVENT_CHN 
call. 

In the following example using event-call channels, process switch may occur 
at different places in the programs. Process A calls YIELD CPU, which gives 
the CPU to Process B only if Process B is ready to run. 
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Process A: 

PROCEDURE Handler(Env_ptr:p_ew_Dlk; 

Data_ptr:p_ex_deta); 


BEGIN 

event2_ptr".[0] := agreeduponvalue; 


(» processing performed here *) 


Interval.sec := 0; (• send event landlately *) 

Interval.nsec :* 0; 

send_event_chn (erring refnumfc, event2_ptr, Interval, clktime); 
to_any :« true; 

YIELD_CPll (errlnt, tojany); 

END; 

BEGIN (• Main program*) 


DECLAREE XCEPHDL (errint, excep_name_l, ^Handler); 
chn_name := •event_channel_l , ; 
exception: = excepnamel; 
receiver := TRUE; 

OPENEVENTJCHN (errint,, chnname, refnuml, exception, receiver); 
chn_name := 'eventcharne i_2'; 
receiver := FALSE; 
exceptions **; 

OPENJEVENTJDHN (errint, chnname, refnime, exception, receiver); 
SENDJEVENTJDHN (errint, refnunC, event2_ptr, interval, clktime); 
to any := true; 

YIELDjCPU (errint, to any); 


5-8 



Operating System Reference Manual 


Exceptions and Events 


Process B: 

PROCEDURE Handler(Env_ptr:p_env_plk; 

Deta_ptr :p_ex_data); 


BEGIN 

event2_ptr\[0] := agreed_upon_value; 


(* processing performed here *) 


interval.sec := 0; (« send event immediately *) 
interval.msec := 0; 

SEND_EVENT_CHN (errlnt, refnuml, event2_ptr, interval, clktime); 
to any -.= true; 

YIELD_CPU (errint, to_any); 

END; 


BEGIN («Hain program «) 

DECLARE_EXCEPJCL (errint, excep_n<wej_l, aH^dler) 

chnname := *event_channel_r; 

exception^ excep name l; 

receiver "= FALSE; 

exceptions * *; 

0PEN_EVENT-CHN (errint, chn_narae, refnuml, exception, receiver); 
chnname s ' event_chamel2' ; 
receiver s TRUE; 

OPENEVENTCHN (errint, chn name, refnum2, exception, receiver); 


END. 
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5.6 The System Clock 

A process can read the system clock time, convert it to local time, or delay 
Its own continuation until a given time. The year, month, day, hair, minute, 
second, and millisecond are available from the clock. The system clock is set 
up through the Workshop shell. For more information, see the Workshop User's 
Guide for the Lisa . 

5.7 Exception Management System Calls 

This section describes all the Operating System calls that pertain to exception 
management A summary of all the Operating System calls can be found in 
Appendix A. The following special types are used in exception management 
calls: 


T_ex_name = STRING[16]; 

Longadr = “longint; 

T_ex_data = Array [0..11] of longlnt; 
T_ex_sts = Record 

ex_occurred_f:boolean; 
exstate: texstate; 
numjexcep:integer; 
hdladr: longadr; 
end; 

T ex state = (enabled, queued, ignored); 
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5 . 7.1 DECLARE_EXCEP_HDL Exception Management System Call 

DECLARE EXCEP HDL ( Var ErrNum:integer; 

Var ExcepName: t_ex_name; 

Entry_Point:LongAdr) 

ErrNum: Error indicator 

Excep_Name: Name of exception 
Entry_Point: Address of exception handler 

DECLARE_EXCEP_HDL sets the Operating System so that the occurrence of 
the exception referred to by Excep_Name causes the execution of the 
exception handler at Entry_Polnt 

Excep Name Is a character string name with up to 16 characters that is 
locally defined In the process and known only to the process and the Operating 
System. If Entry_Point Is nil and Excep_Name specifies a system exception, 
the system default exception handler is used. Any previously declared 
exception handler is dissociated by this call. The exception itself is 
automatically enabled. 

If any Excep_Name exceptions are queued at the time of the 
DECLARE_EXCEP_HDL call, the exception is automatically enabled and the 
queued exceptions are handled by the newly declared handler. 

You can call DECLAREEXCEPHDL with an exception handler address ofnll 
to dissociate your handler from the exception. If there is no system handler 
defined, the program that signals the exception receives an error 201. 
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5.7.2 DISABLE_EXCEP Exception Management System Call 

DISABLEEXCEP (var ErrNun: integer; 

Var ExcepName: t ex name; 

Queue:BooleanJ 

ErrNum: Error Indicator 

Excep_Name: Name of exception to be disabled 

Queue: Exception queuing flag 

A process can explicitly disable trte trapping of an exception by calling 
DISABLE EXCEP. ExcepName Is the name of the exception to be disabled. 
If Queue is true and an exception occurs, the exception Is queued and is 
handled when it Is enabled again, if Queue Is false, the exception Is Ignored. 
When an exception handler Is entered, the state of the exception In question 
Is automatically set to queued. 

If an exception handler is associated through tPEN_EVENT_CHN with an 
event channel and DISABLE_EXCEP is called for that exception, then: 

• If Queue is false, and if an event Is sent to the event channel by 
SEND_EVENT_CHN, the SEND_EVENT_CHN call succeeds, but It Is 
equivalent to not calling SEND_EVENT_CHN at all. 

• If Queue Is true, and If an event Is sent to the event channel by 
SEND EVENT CHN, the SEND_EVENT_CHN call succeeds and a call to 
WA1T_EVENT_CHN receives the event, thus dequeuing the exception. 
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5.7.3 ENABLEEXCEP Exception Management System Call 

ENABLEEXCEP (Var ErrNuni: Integer; 

Var Excep-naine:t_ex_name) 

ErrNum: Error indicator 

Excepjlame: Name of exception to be enabled 

ENABLE EXCEP causes an exception to be handled again. Since the 
Operating System automatically disables an exception when its exception 
handler is entered (see DISABLEJEXCEP), the exception handler should 
explicitly re-enable the exception before it returns to the process. 
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5.7.4 INFCLEXCEP Exception Management system call 

INFOEXCEP (Var ErrNunclnteger; 

Var ExcepName: t_ex_name; 

Var Excep_status:t_ex_sts) 

ErrNum: Error indicator 

Excep_Name: Name of exception 

Excep~Status: Status of exception 

INFO EXCEP returns Information about the exception specified by 

Excep Name. The parameter Excep Status Is a record containing information 

about the exception. This record contains: 

t ex sts = RECORD (* exception status *) 

Exoccurredjf:Boolean;("exception occurred flag *) 
Ex state:t ex state; (» exception status *) 
Num_excep:Integer;(*no. of exceptions queued *) 
Hdl_adr:Longadr; (-exception handler’s address •) 
END; 

Once Ex occurred f has been set to true, only a call to FLUSH EXCEP can 
set it to false. 


5-14 



Operating System Reference Manual 


Exceptions and Events 


5.7.5 SIGNAL_EXCEP Exception Management System Call 

SIGNALEXCEP (Var ErrNum:Integer; 

Var ExcepName: texname; 

Var ExcepData: texdata) 

ErrNum: Error Indicator 

Excep_name: Name of exception to be signaled 

Excep_Data: Information for exception hardier 

A process can signal the occurrence of an exception by calling 
SIGNALEXCEP. The exception handler associated with ExcepJMame Is 
entered. It is passed Excep_Data, a data area containing Information about 
the nature and cause of the exception. The structure of this Information area 
is: 

array[0. .size exdata] of Longint 

SIGNAL EXCEP can be used for user-defined exceptions and for testing 
exception handlers defined to handle system-defined exceptions. 
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5.7.6 flush_EXCEP Exception Management System call 

FLUSH_EXCEP (Var ErrNuro:Integer; 

Var Excep_Name:t_ex_name) 

ErrNum: Error indicator 

Excep_Name: Name of exception whose queue is flushed 

FLUSH EXCEP clears out the queue associated with the exception 
Excep_Name aid resets Its "exception occurred" flag. 
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5.8 Event Management System Calls 

This section describes all the Operating System calls that pertain to event 
management A summary of all the Operating System calls can be found In 
Appendix A. The following special types are used In event management calls: 

Pathname = STRING[255]; 

Texnane = STRING[16]; 

Tchnsts = Record 

chntype: chn_kind; 
num_events:integer; 
open _recv:integer; 
opensend: integer; 
ec_name:pathname; 
end; 

chnkind = (vaitjec, calljec); 

Twaitlist = Record 

length:integer; 

refnum:array [0..10] of integer; 
end; 

Preventblk = 'reventblk; 

Reventblk = Record 

eventheader: t_eheader; 
eventtext: teventtext; 
end; 

Teheader = Record 

send_pid:longint; 
eventtype:longint; 
end; 

T event text = array [0..9] of longint; 

P_s_eventblk = ‘seventblk; 

S_eventblk = Teventtext; 

T imestnpinterval = Record 

sec:longint; 
msec: 0. .999; 
end; 

Timerec = Record 

year:integer; 
day:1..366; 
hour:-23. .23; 
minute:-59..59; 
second:0..59; 
msec:0..999; 

end; 
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5.8.1 KWE_EVENT_CHN Event Management System Call 

MAKEJEVENTJCHN (Var ErrNum:Integer; 

Var Event Chn Narae: Pathname) 

ErrNum: Error indicator 

Event_Chn_Name: Pathname of event channel 

MAKEjEVENTjCHN creates an event channel with the name given In 
Event Chn Name. The name must tie a File System pathname; it cannot he 
null. 
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5.8.2 KILLJEVENT_CHN Event Management System Call 

KILL_EVENT_CHN (Var ErrNum:Integer; 

Var Event_Chn_Name:Pathname) 

ErrNum: Error indicator 

Event_Chn_Name: Pathname of event channel 

To delete an event channel, call KILLJEVENTCHN. The actual deletion Is 
delayed until all processes using the event channel have closed it. In the 
period oetween the KILL_EVENT_CHN call and the channel's actual deletion, 
no processes can open it. A channel can De deleted by any process that 
knows the channel's name. 
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5.8.3 OPENJEVENT_CHN Event Management System Call 

OPEN_EVENT_CHN (Var ErrNum:Integer; 

Var Event Chn Name: Pathname; 
Var Refnum:Integer; 

ExcepName: t_ex name; 
Receiver:Boolean) 


ErrNum: 

Event_ChnJMame: 
RefNum: 
Excep_Name: 
Receiver: 


Error indicator 
Pathname of event channel 
Identifier of event channel 
Exception name, if any 
Access mode of calling process 


OPENEVENTCHN opens an event channel and defines its attributes from trie 
process point of view. RefNum is returned by the Operating System to be 
used in any further references to the channel. 

EventChnName determines whether the event channel is locally or globally 
defined. If it is a null string, the event channel is locally defined. If 
Event_Chn_Name is not null, it is the File System pathname of the channel. 

Excep Name determines whether the channel is an event-wait or event-call 
channel. If it is a null string, the channel is of event-wait type. Otherwise, 
the channel is an event-call channel and Excep_Name is the name of the 
exception that is signaled when an event arrives in the channel. Excep Name 
must be declared before its use in the OPEN_EVENT_CHN call. 

Receiver is a Boolean value indicating whether the process is opening the 
channel as a sender (Receiver is false) or a receiver (Receiver is true). A 
local channel (one with a null pathname) can be opened only to receive 
events. Also, a call-type channel can only be opened as a receiver. 
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5 . 8.4 CLOSE_EVENfT_CHN Event Management system Call 

CLOSE_EVENT_CHN (Var ErrNum:Integer; 

RefNura:Integer) 

ErrNum: Error indicator 

RefNum: Identifier of event channel to be closed 

CLOSE_EVENT_CHN closes the event channel associated with RefNum. Any 
events queued In the channel remain there. The channel cannot be accessed 
until It Is opened again. 

If the channel has previously been killed with KILL_EVENT_CHN, you cannot 
open it after it has been closed. 

If the channel has not been killed. It can be opened by CPEN_EVENT_CHN. 
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5.8.5 INFO_EVENT_CHN Event Management System Call 

INFOEVENTCHN (Var ErrNum: Integer- 
Ref Num: Integer; 

Var Chn lnfo: t_chn_sts) 

ErrNum: Error indicator 

RefNum: Identifier of event channel 

Chn_Info: Status of event channel 

INF0_EVENT_CHN gives a process Information about an event channel. The 
Operating System returns a record, Chnlnfo, with information pertaining to 
the channel associated with RefNum. 

The definition of the type of the Chnjnfo record is: 
t_chn_sts = 

RECORD (* event channel status *) 

Chn_type:Chn_kind; (* wait_ec or call ec *) 

Num_events:integer; (* nuntoer of queued events *) 

Openjrecv:Integer; (* nunber of processes reading channel *) 
Open_send:Integer; (* no. of processes sending to this 

channel *) 

Ec_name:pathname; (* event channel name *) 

END; 
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5.&6 WAlT_EVENT_ON Event M»iagement System Call 

»AIT_EVENT_CHN (Var ErrNun:Integer; 

Var *ait_List: twaitlist; 

Var RefNum:Integer; 

Event_Ptr:p_r_eventblk) 


ErrNum: 
Wait_List: 
RefNum: 
Event Ptr: 


Error indicator 

Record with array of event channel refnums 
Identifier of channel that had an event 
Pointer to event data 


WAIT_EVENT_CHN puts the calling process In a waiting state pending the 
arrival of an event In one of the specified channels. WaitJList Is a pointer to 
a list of event channel identifiers. When an event arrives in any of these 
channels, the process is made ready to execute. RefNum identifies which 
channel got the event, and Event_Ptr points to the event itself. 

A process can wait for any Boolean combination of events. If it must wait 
for any event from a set of channels (an OR condition), it should call 
WAIT_EVENT_CHN with Wait_List containing the list of event channel 
identifiers. If, on the other hand, it must wait for all the events from a set 
of channels (an AND condition), then for each channel in the set, 
WAITJEVENT_CHN should De called with WaitJJst containing just that 
channel identifier. 

The structure of twaitlist is: 

RECORD 

Length:Integer; 

Refnum:Array[0..sizej»aitllst] of integer; 

END; 

Event_Ptr is a pointer to a record containing the event header and the event 
text. Its definition is: 

Preventblk = "reventblk; 

R_eventblk = Record 

eventheader: teheader; 
event_text:t_event_text; 
end; 

T_eheader = Record 

send _pid:longint; 
event_type:longint; 
end; 

T_event_text = array [0..9] of longint; 

Send_pid is the process id of the sender. 
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Currently, tne possible event type values are: 

1 - Event sent by user process 

2 - Event sent by system 

When you receive the SYS_SON_TERM event, the first longint of the event 
text contains the termination cause of the son process. The cause Is same as 
that given In the SYS_TERM1NATE exception given to the son process. The 
rest of the event text can be filled by the son process. 

If you call WAIT EVENT CHN on an event-call channel that has queued 
events, the event Is treated just like an event In an event-wait channel, if 
WAIT_EVENT_CHN is called on an event-call channel that does not have any 
queued events, an error is returned. 
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5.8.7 FLUSH_EVENT_CHN Event Management system call 

FLUSH JEVEKT_CHN (Var ErrNum:integer; 

RefNum:Integer) 

ErrNum: Error indicator 

RefNum: Identifier of event channel to be flushed 

FLUSH_EVENT_CHN clears out the specified event channel. All events 
queued in the channel are removed. If FLUSH EVENT CHN is called by a 
sender, it has no effect. 
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5.8.8 SEND_EVENT_CHN Event Management system Call 

SEND EVENT CHN (Var ErrNum: Integer; 

RefNum:Integer; 

Event_Ptr:p_s_eventblk; 
Interval: T imestnp_interval; 
Clktime:Time_rec) 


ErrNum: 

RefNum: 

Event_Ptr: 

Interval: 

Clktime: 


Error indicator 
Channel for event 
Pointer to event data 
Timer for event 
Time data for event 


SEND EVENT CHN sends an event to the channel specified by RefNum. 
Event_Ptr points to the event that is to be sent. The event data area 
contains only the event text; the header is added by the system. 

If the event is of the event-wait type, the event is queued. Otherwise the 
operating System signals the corresponding exception for the process receiving 
the event. 

if the channel is opened by several senders, the receiver can sort the events 
by the process identifier, which the Operating System places in the event 
header. Alternatively, the senders can place predefined identifiers, which 
identify the sender, in the event text. 

The Interval parameter indicates whether the event is a timed event. 
_ NOTE _ 

Timed events will not be supported in future releases of the Operating 
System. The Interval and Clktime parameters will be ignored In future 
releases. If you want your software to be upward-compatible, always 
set both fields of the Interval parameter to zero. 


Tlmestmp lnterval is a record containing a second and a millisecond field. If 
both fields are 0, the event is sent immediately. If the second given is less 
than 0, the millisecond field is ignored and the Timejrec record is used. If 
the time in the Timejrec has already passed, the event is sent immediately. 

If the millisecond field is greater than 0, and the second field is greater than 
or equal to 0, the event is sent that number of seconds and milliseconds from 
the present. 

A process can time out a request to another process by sending itself a timed 
event and then waiting for the arrival of either the timed event or an event 
indicating the request has been served. If the timed event Is received first, 
the request has timed out. A process can also time its own progress by 
periodically sending itself a timed event through an event-call event channel. 
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5.9 Clock System Calls 

This section describes all the Operating System calls that pertain to the clock. 

A summary of all the Operating System calls can be found in Appendix A. 

The following special types are used in clock calls: 

T imestnpinterval = Record 

sec:longint; 
msec: 0. .999; 
end; 

Timerec = Record 

year:integer; 
day:1..366; 
hour:-23..23; 
minute:-59..59; 
second:0..59; 
msec:0..999; 
end; 

Hourrange = -23.. 23 

Minute_range = -59..59; 
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5.9.1 DELAY_T1ME Clock System call 

OELAYTIME (Var ErrNum: Integer- 

Interval : T imestmpinterval; 

Clktime: Timejrec) 

ErrNum: Error indicator 

Interval: Delay timer 
Clktime: Time information 

OELAY_TIME stops execution of the calling process for the number of seconds 
and milliseconds specified In the Interval record. If this time period is zero, 
DELAY TIME has no effect If the period is less than zero, execution of the 
process is delayed until the time specified by Clktime 
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5.9.2 GET_T1ME Clock System call 

GET_TIME (Var ErrNum:integer; 

Var Sy s_Time: T lme_rec) 

ErrNum: Error indicator 

Sys_Time: Time information 

GET_TIME returns the current system clock time In the record Sys_Time. The 

msec field of Sys_Ttme always contains a zero on return. 
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5.9.3 SET_local_time_DIFF Clock System call 

SET_LOCAL_TIME_DIFF (Var ErrNum:Integer; 

Hour: Hourrange; 

Minute:Minute jrange) 

ErrNum: Error indicator 

Hour: Number of hours difference from the system clock 

Minute: Number of minutes difference from the system clock 

SET_LOCAL_TlMEJDIFF Informs the Operating System of the difference in 
hours and minutes between the local time and the system clock. Hour and 
Minute can be negative. 
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5.9.4 C0NVERT_TIME Clock System call 

convert time (War ErrNum:Integer; 

Var Sys_T ime: T imerec; 

Var Local T ime: Timerec; 

To_sys:Boolean) 

ErrNum: Error Indicator 
Sys_Time: System clock time 

Local_Time: Local time 

To_Sys: Direction of time conversion 

C0NVERT_TIME converts between local time and system clock time. 

To Sys is a Boolean value indicating in which direction the conversion is to 
go. If To_Sys is true, the system takes the time data in Local_Time and puts 
the corresponding system time in Sys_Time. If TojSys is false, the system 
takes the time data in Sys_Tlme and puts the corresponding local time in 
Local_Time. Both time data areas contain the year, month, day, hour, minute, 
second, and millisecond. 
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Every Lisa system is configured using the Preferences tool. Preferences 
places the configuration state of the system in a special part of the system’s 
memory called parameter memory Although parameter memory is not 
contained on a disk, it is supplied with battery power so that the contents are 
kept even when the system is turned off. The batteries are charged as long 
as the Lisa is plugged in, even if the unit is powered off. If line power is 
lost, the batteries will keep parameter memory secured for several hours. In 
addition, every time parameter memory is changed, a copy of the new data is 
made on the boot disk. If the contents of parameter memory are lost, this 
disk copy is automatically restored to parameter memory. 

Since the devices actually connected may differ from the configuration stored 
in parameter memory, three calls are provided that allow programs to request 
information about the configuration of the system. 

_ NOTE _ 

Configuration System Calls will be changed in future releases of the 
Operating System. Do not use these calls if you want your software to 
be upward-compatible. 


6.1 Configuration System Calls 

This section describes all the Operating System calls that pertain to 
configuration. A summary of all the Operating System calls can be found in 
Appendix A. Special data types used by configuration calls are defined along 
with the calls. 
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6.1.1 CARDS_EQUIPPED Configuration System Call 

CARDS_EQUIPPED (Var ErrNuncinteger; 

Var In_Slot:Slot_array) 

ErrNum: Error code 

In_Slot: Identifies the types of cards configured 


This call returns an array showing the types of cards which are In the various 
card slots. 

The definition of Slot array is: 

siotjarray = array [1..3) of card_types; 

where: 

card types » (no card, 

apple_cartL 

nj»rt_card, 

net_cant 

lasercard); 
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6.1.2 GET_CONFIG_NAME Configuration system Call 

GET_CONFIG_NM€ (Var Ermum: Integer; 

Devpostn:Tports; 

Var Devname:EName) 

Errnum: Error code 

Devpostn: A port identifier 

Devname: The name of the device attached to the port 

This call returns the name of the device configured at the port given In 
Devpostn. see OSBOOTVOL for the definition of Tports. Type E_Name Is 
defined as: 

E_Name = STRING [32]; 
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6.13 OSBOOTVOL Configuration System call 

0S800TV0L (Var ErrNun:Integer) : Tports 

ErrNum: Error code 

Tports: Identifies the port to which the boot volume is attached 

OSBOGTVOL Is a function that returns the Identifier for the port attached to 
the boot volume. This port might not be the port configured for the boot 
volume, since it is possible for the user to override the default boot. Note 
that the port Identifier is not the same as the device name. You can use 
GET_CONFIG_NAME to find out the name of the device attached to the port. 

Tports is a set that has this definition: 

Tports = (uppertwig, lowertwig, parallel, 
siotli, siotiz, slcti3, slotl4, 

SlOt21, SlOt22, SlOt23, SlOt24, 

slot31, slot32, slot33, slot34, 

seriala, serialb, main_console, alt console, 

tjnouse, t speaker, t_extral, t_extra2, t extra3); 
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Appendix A 

Operating System Interface Unit 


UNIT syscall; (* system call definitions unit *) 

INTRINSIC; 

INTERFACE 


CONST 

maxename = 32; (» maximum length of a file system object name *) 

max_pathname = 255; (* maximum length of a file system pathname *) 

maxlabelsize = 128; (* maximum size of a file label, in bytes *) 

len exname = 16; (* length of exception name *) 

sizeexdata = 11; (* 48 bytes, exception data block should have the 

same size as r_eventblk, received event block *) 

size etext = 9; (* event text size - 40 bytes *) 

size vaitlist = 10; (* size of wait list - should be same as reqptr_list *) 


(« exception kind 
callterm = 0; 
ended = 1; 
self_killed = 2; 
killed = 3; 
fthrterm = 4; 
badsyscall = 5; 
badjermum = 6; 
svap_error = 7; 
stkoverf low = 8; 
dataoverf low = 9; 
parityjerr = 10; 


definitions for 1 SYS TERMINATE' exception 
(* process called terminate_process 
(* process executed 'end 1 statement 
(« process called kill_process on self 
(* process was killed by another process 
(* process's father is terminating 
(* process made invalid sys call - subcode bad 
(* process passed bad address for ermum parm 
(* process aborted due to code swap-in error 
(* process exceeded max size (+T mn) of stack 
(~ process tried to exceed max data space size 
(* process got a parity error vhile executing 


*) 

*) 

*) 

*) 

*) 

*) 

*) 

*) 

") 

*) 

*) 


def_div_zero 

def_value_oob 

defjovfv 

def_nmi_key 

def_range 

def str index 


11;(* default handler for div zero exception was called *) 
12; (* " for value oob exception *) 
13; (* " for overflow exception *) 
14; (* " for NMI key exception *) 
15;(* " for 'SYS_VALUE_OOB * excep due to value range err *) 
16;(« " for 'SYS_VALUE_006' excep due to string index err *) 
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busjerror = 21; (* bus error occurred *) 
addrjerror « 22; (* address error occurred *) 
illgLinst = 23; (* Illegal Instruction trap occurred *) 
privviolation = 24; (* privilege violation trap occurred *) 
line_10l0 = 26; (* line 1010 emulator occurred *) 
line_llll = 27; (* line 1111 emulator occurred *) 

unexpectedjex = 29; (* an unexpected exception occurred *) 


div zero = 31; (* exception Kind definitions for hardware exception *) 

value_oob = 32; 

ovfw - 33; 

nmikey = 34; 

valuejrange = 35; (* excep kind for value range and string index error *) 

str index = 36; (* Note that these two cause 'SYSVALUEOOB' excep *) 

(*oevice_control functions*) 


dvParity = 1; 
dvOutOTR = 2; 
dvOutXON = 3; 
dvOutOelay = 4; 
dvBaud = 5; 
dvInVait = 6; 
dVlnDTR = 7; 
dvInXON - 8; 
dvTypeahd = 9; 
dvOiscon = 10; 
dvOutNoHS = 11; 
dvErrStat = 15; 
dvGetEvent = 16; 
dvAutoLF = 17; 
dvOlskStat = 20; 
dvDiskSpare = 21; 


(*RS-232*) 

(*RS-232*) 

(*RS-232*) 

(-RS-232*) 

(•RS-232*) 

(-RS-232, CONSOLE*) 

(-RS-232*) 

(•RS-232*) 

(*RS-232*) 

(*RS-232*) 

(*RS-232*) 

(•PROFILE*) 

(•CONSOLE*) 

("RS-232, CONSOLE, PARALLEL PRINTER*) (-not yet*) 
("DISKETTE, PROFILE*) 

(•DISKETTE, PROFILE*) 


TYPE 

pathname = string [max_pathname]; 
ename = string [maxjename]; 
namestring = string [20],- 
proclnfoRec = record 
progpathname : pathname; 
glotoal_id : longint; 

father_ld : longing- 

priority : 1..255; 

state : (pactlve, psuspended, pwalting); 

data in : boolean 

end; 
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Tdstype = (ds_shared, ds_private); (* types of data segments *) 

dsinfoRec = record 

memsize : longint; 
disc_size: longint; 
numb_open : integer; 
ldsn : integer; 
boundF : boolean; 
presentF : boolean; 
creatorF : boolean; 
rwaccess : boolean; 
segptr : longint; 
volname: ertame; 

end; 


t_ex_name = string [lenexname]; 
longadr = "longint; 

t ex state = (enabled, queued, ignored); 
plex_data = "t_exjlata; 

t_ex_data = array [0..size_exdata] of longint; 

texsts = record 

ex occurred f : boolean; 

ex_state : t ex state; 

num excep : integer; 

bdl adr : longadr; 

end; 


(« exception name *) 

(* exception state «) 

(« exception data blk «) 

(* exception status «) 

(* exception occurred flag *) 

(» exception state *) 

(« nuntoer of exceptions q’ed «) 

(* handler address *) 


p_env_blk = "env_blk; 
envblk = record 
pc : longint; 
sr : integer; 
dO : longint; 
dl : longint; 
d2 : longint; 
d3 : longint; 
d4 : longint; 
d5 : longint; 
d6 : longint; 
d7 : longint; 
aO : longint; 
al : longint; 
a2 : longint; 
a3 : longint; 
a4 : longint; 
a5 : longint; 
a6 : longint; 
a7 : longint; 
end; 


(* environment block to pass to handler *) 
{* progran counter «) 
(* status register *) 
(* data registers 0-7 *) 


(* address registers 0-7 


*) 
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ptermexdata = *term_ex_data; 

term_ex_data = record (* terminate exception data block *) 

case excep_kind : longint of 
cail_term 
ended, 

self_killed, 

killed, 

fthr_tem 

bad_syscall, 

bad_errnum 

swap_error, 

stk_overflow, 

dataoverflow, 

parity_err : (); (* due to process termination *) 

lllg_inst, 

priv_violation, (* due to illegal instruction, privilege 

violation *) 

line_l010, 

line_llll, (* due to line 1010, nil emulator *) 

defdivzero, 

def_value_oob, 

defovfv, 

def_nmi_key (* terminate due to default handler for hardware 

exception *) 

: (sr : integer; 

pc : longint); (* at the time of occurrence *) 

def_range, 

def_str_index (* terminate due to default handler for 

’SYS_VALUE_00B' excep for value range or string 
index error «) 

: (value_check : integer; 
upper_bound : integer; 
lower_bound : integer; 
returnjac : longint; 
caller_a6 : longint); 
buserror, 

addr_error (* due to bus error or address error *) 

: (fun field : packed record (« one integer «) 

filler : 0..$7ff; (* 11 bits *) 

r_w_flag : boolean; 
i_n_flag : boolean; 
fun_code : 0..7; (* 3 bits *) 


end; 
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accessadr : longint; 
inst_register : integer; 
sr_error : integer; 
pc_error : longint); 

end; 

p_hard_ex_data = / 'hard_ex_data; 

hard ex data = record (* hardware exception data block *) 

case excep_kind : longint of 

divzero, valueoob, ovf* 

: (sr : integer; 
pc : longint); 
vaiue_range, str_index 
: (valuecheck : integer; 
upper jxxnd : integer; 

] ower bound : integer; 
return jk : longint; 
caller_a6 : longint); 

end; 


accesses - (dread, dwrite, append, private, global refnum); 

mset = set of accesses; 

iomode = (absolute, relative, sequential); 

UID = record (“unique id*) 
a,b: longint 

end; 

timestwp_interval = record (* time interval *) 

sec : longint; (* number of seconds *) 

msec : 0..999; (* number of milliseconds within a second *) 

end; 

info type = (device t, volume_t, object t); 

devtype = (diskdev, pascalbd, seqdev, bitbkt, non io); 

filetype = (undefined, MDOFfile, rootcat, freelist, badblocks, sysdata, 

spool, exec, usercat, pipe, bootfile, swapdata, swapcode, ramap, 
userflle, killedobject); 

entrytype= (emptyentry, catentry, linkentry, fileentry, pipeentry, ecentry, 
killedentry); 
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fs_lnfo = record 
name : ejname; 
dlr_path : pathname; 
machlneid : longint; 
fsjoverhead : integer; 
result_scavenge : integer; 
case otype : info_type of 
device_t, volumet: ( 
iochamel : integer; 
devt : devtype; 
slot_no : integer; 
fs_size : longint; 
vol slze : longint; 
blockstructured, mounted : boolean; 
opencount : longint; 

privatedev, remote, lockeddev : boolean; 
mount.pending, unmount.pending : boolean; 
volname, password : e.name; 
fsversion, volnum : integer; 
volid : UID; 
backup_volld : UID; 

blocksize, datasize, clustersize, filecount : integer; 
label_size : integer; 
freecount : longint; 

DTVC, DTCC, DTVB, DTVS ; longint; 

master copy id, copy_thread : longint; 

overmount_stanp : UID; 

boot code : integer; 

bootjenvlron : integer; 

privileged, writejjrotected : boolean; 

master, copy, copy_flag, scavenge_flag : boolean; 

vol_left_mounted : boolean ); 

object t : ( 
size : longint; 

psize : longint; (* physical file size in bytes *) 

lpslze : integer; (* logical page size in bytes for this file *) 

ftype : filetype; 
etype : entrytype; 

DTC, DTA, DTh, DIB, DTS : longint; 
refnum : integer; 
fmark : longint; 
acmode : mset; 

nreaders, nwriters, nusers : integer; 
fuld : UID; 
user_type : integer; 
user_subtype : integer; 
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systero_type : integer,- 
eof, safetyon, ksvitch : boolean; 
private, locked, protected, master_flie : boolean; 
file_scavenged, file_closed_by_OS, file_left_open:boolean) 
end; 


detype = record 

deversion : integer,- 
decode : integer; 

dedata : array [0..9] of longint; (* user/driver defined data «) 

end; 

t_vaitlist = record (* wait list *) 

length : integer,- 

refnum : array [0..sizej»aitlist] of integer- 

end; 

t eheader = record (* event header «) 

send_pld : longint; (« sender's process id *) 

eventtype : longint; (* type of event *) 

end; 


t_event_text = array [0.,size_etext] of longlnt; 
p_r_eventblk = "reventblk; 
r_eventblk = record 

eventheader : t_eheader,- 
event text : t_event_text; 

end; 


pseventblk = ‘seventblk; 
s_eventblk = t_event_text; 

time_rec = record 
year : integer- 

day : 1..366; (* Julian date *) 

hour : -23..23; 

minute : -59..59; 

second : 0..59; 

msec : 0. .999; 

end; 
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chn_kind = (vaitjec, calljec); 
tchnsts = record 

chn_type : chnjdnd; 
numevents : integer; 
open_recv : integer; 
open_send : integer; 
ec_name : pathname; 

end; 

hour_range « -23..23; 
minute jrange = -59..59; 


(» channel status «) 

(* channel type *) 

(* number of events queued *) 
(* number of opens for receiving *) 

* number of opens for sending *) 

* event channel name *) 


{configuration stuff: } 

tports = (uppertvig, lomertvig, parallel, 
slotll, siotl2, slotl3, slotl4, 
slot21, slot22, Sl0t23, slot24, 

SlOt31, Sl0t32, Slot33, SlOt34, 

seriala, serialb, main_console, alt_consoie, 

t_mouse, t speaker, tjextral, t_extra2, t_extra3); 

cardtypes = (nojcard applejcard, n_port_card, netjcard, laserjcard); 

slot_array = array [1..3] of card_types; 


{ Lisa Office System parameter memory type } 

pmByteOnique = -128..127; 

phenftec = array [1. .62] of pnByteUhique; 


(* File System calls •) 

procedure MAKE FILE (var ecode:integer; var path: pathname; 
label_size:integer); 

procedure HAKE.PIPE (var ecode:integer; var path:pathname; 
labei_size:integer); 

procedure MAKE_CATALOG (var ecode:integer; var path:pathname; 
label_slze:integer); 

procedure MAKEJLINK (var ecode:integer; var path, ref:pathname; 
label_size:integer); 
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procedure KILL_0BJECT (var ecode:integer; var path:pathname); 

procedure unkill_file (var ecode:integer; refnun:integer; var 
new_name:e_name); 

procedure OPEN (var ecode:integer; var path:pathname; var refnum:integer; 
manip:mset); 

procedure CL0SE_0BJECT (var ecode integer; refnumdnteger); 

procedure READ_DATA (var ecode:integer; refnun:integer; data_addr:longint; 

count :longint; var actualdongint; modedomode; 
offset dongint); 

procedure write_data (var ecode:integer; refnuntInteger; data_addr:longlnt; 

count:longint; var actual:longint; modedomode; 
offsetdongint); 

procedure FLUSH (var ecode:integer; refnum:integer); 

procedure LOOKUP (var ecode:integer; var patfcpathname; var 
attributes:fs_info); 

procedure INFO (var ecode: integer; ref nun: integer; var refinfo.-fsinfo); 

procedure ALLOCATE (var ecodednteger; refnum integer; contiguous:boolean; 
countdongint; var actualdongint); 


procedure TRUNCATE (var ecodednteger; refnumdnteger); 

procedure COflPACT (var ecodednteger; refnumdnteger); 

procedure RENAME_ENTRY ( var ecodednteger; var path pathname; var 
newname-.e_name ); 

procedure READLABEL ( var ecodednteger; var path:pathname; 

data_addr:longint; countdongint; var actualdongint ); 

procedure WRITE_LABEL ( var ecodednteger; var patrrpathname; 

data addrdongint; countdongint; var actualdongint ); 

procedure MOUNT ( var ecodednteger; var vname : e nane; var password : 
e_name ;var devname : e_name); 

procedure UNMOUNT ( var ecodednteger; var vname : e_name ); 
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procedure SET WORKING DIR ( var ecode:integer; var path:pathname ); 

procedure GET_WORKING_DIR ( var ecode:integer; var path:pathname ); 

procedure SETSAFETY (var ecode:integer;var path:pathname;on_off:boolean ); 

procedure DEVICECONTROL ( var ecode:integer; var path:pathname; 
var cparm : detype ); 

procedure RESETCATAIOG (var ecodednteger; var path:pathname); 
procedure GET NEXT ENTRY (var ecodednteger; var prefix, entry:e_name); 
procedure SET_FILE_INFO (var ecode dnteger; refnumdnteger; fsi:fs_info); 

(* Process Management system calls ») 
function My_ID:longint; 

procedure Info_Process (var ermumdnteger; proc_iddongint; var 
proc_info:procinfoRec); 

procedure Yield_CPU (var er mum integer; to_any:boolean); 

procedure SetPriority Process (var ermuntinteger; prociddongint; 
ne»_priorltydnteger); 

procedure Suspend Process (var ermuntinteger; prociddongint; 
suspf ani ly:boolean ); 

procedure ActivateProcess (var ermunt integer; prociddongint; 
act_family:boolean); 

procedure Kill_Process (var ermuntinteger; proc_ld:longlnt); 

procedure Terminate_Process (var ermuntinteger; event_ptr:p_s_eventblk); 

procedure Make_Process (var ermuntinteger; var proc_iddongint; var 
progfile:pathname; var entryname:namestring; 
evnt_chn_refnuntinteger); 
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(* Memory Management system calls *) 

procedure make_dataseg(var errnum: Integer; var segname: pathname; mem_size y 
discsize: longint; var refnum: integer; var secptr: 
longint; ldsn: integer; dstype: Tdstype); 

procedure kiil_dataseg (var errnum:integer; var segname:pathname); 

procedure open dataseg (var erramt integer; var segname:pathname; var 

refnunt integer; var segptrilongint; ldsn-.integer); 

procedure closedataseg (var errnum: integer; refnunt integer); 


procedure size_dataseg (var erramt integer; refnunt integer; 

deltamemsize:longint; var newmemsize-.longint; 
deltadiscsize: longint; var newdiscsize: longint); 

procedure infojlataseg (var erramt integer; refnunt integer; var 
ds inf o:ds inf oRec ); 

procedure setaccessdataseg (var errnuntinteger; refnuntinteger; 
readonlyiboolean); 

procedure unoinddataseg (var erniuntinteger; refnunt integer); 

procedure bind_dataseg(var errnunt integer; refnuntinteger); 

procedure info_ldsn (var erramtinteger; ldsn: integer; var refnum: integer); 

procedure flush dataseg(var errnum: integer; refnum: integer); 

procedure mem_info(var errnum: integer; var swapspace, dataspace, 
curcodesize, maxcodesize: longint); 

procedure info_address(var errnum: integer; address: longint; var refajm: 
integer); 


(* Exception Management system calls *) 

procedure declare_excep_hdl (var errnunt integer; var excepnamertexname; 
entry _point:iongadr); 

procedure disahle_excep (var errnuntinteger; var excep_name:t_ex_name; 
queueiboolean); 
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procedure enable_excep (var errnuntinteger; var excep_nameit_ex_name); 

procedure signalexcep (var errnuntinteger; var excep_nameit_ex_name; 
excep_datait_ex_data); 

procedure info excep (var errnuntinteger; var excep_nameit_ex_name; var 
excep_status:t_ex_sts); 

procedure flush_excep (var errnuntinteger; var excep_name: t_ex jiame); 


(» Event Channel management system calls *) 

procedure makeeventchn (var errnuntinteger; var eventchnnameipathname); 

procedure kill_event_chn (var errnuntinteger; var eventchnnameipathname); 

procedure open event chn (var errnuntinteger; var event chn nameipathname; var 
refnuntinteger; var excep_nameit_ex_name; 
receiveriboolean); 

procedure close_event_chn (var errnuntinteger; refnuntinteger); 

procedure info_event_chn (var errnuntinteger; refnuntinteger; var 
chn_inf oit_chn_st s ); 

procedure wait event chn (var errnuntinteger; var wait listitjuaitlist; var 
refnuntinteger; eventjDtrip r eventblk); 

procedure flush event chn (var errnuntinteger; refnuntinteger); 

procedure send event chn (var errnuntinteger; refnuntinteger; 

event_ptr:p_s_eventblk; intervaiitimestmp_interval; 
clktimeitime_rec); 


(* Timer functions system calls *) 

procedure delay_time (var errnuntinteger; intervalitimestmp interval; 
clktimeitlme_rec); 

procedure get_time (var errnuntinteger; var gmt_timeitime_rec); 

procedure set_local_time_diff (var errnuntinteger; hour:hour_range; 
minuteiminute_range); 


A-12 



Operating System Reference Manual 


Operating System interface unit 


procedure convert_time (var ermurtinteger; var gmt_time:time_rec; var 
local_time:time_rec; tojgmt-.boolean); 


{configuration stuff} 

function OSBOOTVOL(var error : integer) : tports; 

procedure 6ETCONFIG_N AME ( var error:integer; devpostnrtports; var 
devname:e_name); 

procedure CARDS_EQUIPPED(var error:integer; var in_slot:slot_array); 
IMPLEMENTATION 

procedure MAKE_FILE; external; 
procedure make_PIPE; external; 
procedure MAKE_CATALOG; external; 
procedure MAKEJ.INK; external- 
procedure KILL_OBJECT; extemal; 
procedure OPEN; external- 
procedure CLOSE_OBJECT; external; 
procedure READ_DATA; external; 
procedure WRI TE_DATA; external; 
procedure FLUSH; external; 
procedure LOOKUP; external; 
procedure INFO; external; 
procedure ALLOCATE; external; 
procedure TRUNCATE; external; 
procedure COMPACT; external; 
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procedure RENAMEENTRY; external; 
procedure READLABEL; external; 
procedure *RITE_LA8EL; external- 
procedure MOUNT; external; 
procedure UNMOUNT; external- 
procedure SETJWRKINGDIR; external; 
procedure GET_K0RKING_DIR; external- 
procedure SETSAFETY; external; 
procedure OEVICE_CONTROL; external- 
procedure RESETCATALOG; external; 
procedure GETNEXTENTRY; external; 
procedure GETDEVNAME; external- 

function My_ID; external- 
procedure lnfo_Process; external; 
procedure Yield_CPU; external- 
procedure SetPriority_Process; external; 
procedure Suspend Process; external; 
procedure Activate_Process; external- 
procedure Kill_Process; external- 
procedure Terminate Process; external- 
procedure Make_Process; external- 
procedure Sched_Class; external; 
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procedure makedataseg; external; 
procedure killdataseg; external; 
procedure opendataseg; external; 
procedure closedataseg; external; 
procedure sizedataseg; external; 
procedure lnfodataseg; external; 
procedure setaccessjdataseg; external; 
procedure unblndjdataseg; external; 
procedure blnd dataseg; external; 
procedure infoldsn; external- 
procedure flush dataseg; external; 
procedure raem_info; external; 

procedure declare_excep_ndl; external- 
procedure dlsable_excep; external; 
procedure enatileexcep; external; 
procedure signaljexcep; external; 
procedure info_excep; external; 
procedure flush_excep; external; 

procedure make_event_chn; external- 
procedure killeventchn; external- 
procedure openeventchrv external- 
procedure c lose event chn; external; 
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procedure info_event_chrv external; 
procedure walt_event_cfirv external; 
procedure flush_event_chn; external; 
procedure send_event_cfm; external; 

procedure delay_time; external- 
procedure gettime; external- 
procedure set_local_time_diff; external; 
procedure converttlme; external- 
procedure set_file_lnfo; external- 
function ENA8LEDBG; external; 
function 0S800TV0L; external- 
procedure GETCONFIGNAME; external; 
function DISK LIKELY; external- 
procedure CARDS_EQUIPPED; external; 
procedure Read_PHenu external; 
procedure irite_Pflent- external; 
end. 
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SYSOVERFLOW 

sys_value_oob 

SYS_ZERO_DIV 

SYS_TERMINATE 


Overflow exception. Signaled when the TRAPV instruction is 
executed and the overflow condition is on. 


Value-out-of-bound exception. Signaled when the CHK 
instruction is executed and the value is less than 0 or greater 
than upper Pound. 

Division Py zero exception. Signaled when the DIVS or D1VU 
instruction is executed and the divisor is zero. 


Termination exception. Signaled when a process is to be 
terminated. 
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SYS_SON_TERM "Son terminate" event type. If a father process has created a son 
process with a local event channel, this event is sent to the 
father process when the son process terminates. 
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Appendix D 
Error Messages 


-6081 End of exec file input 
-6004 Attempt to reset text file with typed-file type 
-6003 Attempt to reset nontext file with text type 
-1885 ProFile not present during driver initialization 
-1882 ProFile not present during driver initialization 
-1176 Data in the object have been altered by Scavenger 
-1175 File or volume was scavenged 

-1174 File was left open or volume was left mounted, and system crashed 
-1173 File was last closed by the OS 
-1146 Only a portion of the space requested was allocated 

-1063 Attempt to mount boot volume from another Lisa or not most recent boot 
volume 

-1060 Attempt to mount a foreign boot disk following a temporary unmount 
-1059 The bad block directory of the diskette is almost full or difficult to read 
-696 Printer out of paper during initialization 
-660 Cable disconnected during ProFile initialization 
-626 Scavenger indicated data are questionable, but may be OK 
-622 Parameter memory and the disk copy were both invalid 
-621 Parameter memory was invalid but the disk copy was valid 
-620 Parameter memory was valid but the disk copy was invalid 
-413 Event channel was scavenged 
-412 Event channel was left open and system crashed 
-321 Data segment open when the system crashed. Data possibly invalid. 

-320 Could not determine size of data segment 

-150 Process was created, but a library used by program has been scavenged and 
altered 

-149 Process was created, but the specified program file has been scavenged and 
altered 

-125 Sepcified process is already terminating 
-120 Specified process is already active 
-115 Specified process is already suspended 

100 Specified process does not exist 

101 Specified process is a system process 
110 Invalid priority specified (must be 1..225) 

130 Could not open program file 

131 File System error while trying to read program file 

132 Invalid program file (incorrect format) 

133 Could not get a stack segment for new process 

134 Could not get a syslocal segment for new process 

135 Could not get sysglobal space for new process 

136 Could not set up communication channel for new process 
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138 Error accessing program file while loading 

141 Error accessing a library file while loading program 

142 Cannot run protected file on this machine 

143 Program uses an intrinsic unit not found in the Intrinsic Library 

144 Program uses an intrinsic unit whose name/type does not agree with the 
Intrinsic Library 

143 Program uses a shared segment not found in the intrinsic Library 

146 Program uses a shared segment whose name does not agree with the Intrinsic 
Library 

147 No space in syslocal for program file descriptor during process creation 

148 no space in the shared iu data segment for the program’s shared IU globals 

190 No space in syslocal for program file description during List_LibFiles 
operation 

191 Could not open program file 

192 Error trying to read program file 

193 Cannot read protected program file 

194 Invalid program file (incorrect format) 

195 Program uses a shared segment not found in the Intrinsic Library 

196 Program uses a shared segment whose name does not agree with the Intrinsic 
Library 

198 Disk I/O error trying to read the intrinsic unit directory 

199 Specified library file number does not exist in the Intrinsic Library 

201 No such exception name declared 

202 No space left in the system data area for Declare_Excep_Hdl or 
Signal_Excep 

203 Null name specified as exception name 

302 invalid LDSN 

303 No data segment bound to the LDSN 

304 Data segment ai ready bound to the L DSN 

306 Data segment too large 

307 input data segment path name is invalid 

308 Data segment already exists 

309 insufficient disk space for data segment 

310 An invalid size has been specif led 

311 Insufficient system resources 

312 Unexpected File System error 

313 Data segment not found 

314 invalid address passed to lnfo_Address 

315 Insufficient memory for operation 

317 Disk error while trying to swap in data segment 

401 Invalid event channel name passed to Make_Event_Chn 

402 No space left in system global data area for Open_Event_Chn 

403 No space left in system local data area for Open_Event_Chn 

404 Non-block-structured device specified in pathname 

405 Catalog is full In Make_Event_Chn or 0pen_Event_Chn 

406 No such event channel exists in Kill_Event_Chn 
410 Attempt to open a local event channel to send 
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411 Attempt to open event channel to receive when event channel has a receiver 
413 Unexpected File System error in Open_Event_Chn 

416 Cannot get enough disk space for event channel In Open_Event_Chn 

417 unexpected File System error In ciose_Event_Chn 

420 Attempt to wait on a channel that the calling process did not open 

421 Wait_Event_Chn returns empty because sender process could not complete 

422 Attempt to call walt_Event_Chn on an empty event-call channel 

423 Cannot find corresponding event channel after being blocked 

424 Amount of data returned while reading from event channel not of expected 
size 

425 Event channel empty after being unblocked, Wait_Event_Chn 

426 Bad request pointer error returned in Wait_Event_Chn 

427 waltjjst has illegal length specified 

428 Receiver unblocked because last sender closed 

429 Unexpected File System error In wait_Event_Chn 

430 Attempt to send to a channel which the calling process does not have open 

431 Amount of data transferred while writing to event channel not of expected 
size 

432 Sender unblocked because receiver closed in Send_Event_Chn 

433 Unexpected File System error in Send_Event_Chn 

440 Unexpected File System error in Make_Event_Chn 

441 Event channel already exists in Make_Event_Chn 
445 Unexpected File System error in Kiii_Event_Chn 
450 Unexpected File System error in Flush_Event_Chn 

530 Size of stack expansion request exceeds limit specified for program 

531 Cannot perform explicit stack expansion due to lack of memory 

532 Insufficient disk space for explicit stack expansion 
600 Attempt to perform I/O operation on non I/O request 
602 No more alarms available during driver initialization 

605 Call to nonconfigured device driver 

606 Cannot find sector on floppy diskette (disk unformatted) 

608 Illegal length or disk address for transfer 

609 Call to nonconfigured device driver 

610 No more room in sysglobal for I/O request 

613 Unpermitted direct access to spare track with sparing enabled on floppy 
drive 

614 No disk present in drive 

615 Wrong call version to floppy drive 

616 Unpermitted floppy drive function 

617 Checksum error on floppy diskette 

618 Cannot format, or write protected, or error unclamping floppy diskette 

619 No more room in sysglobal for I/O request 

623 Illegal device control parameters to floppy drive 
625 Scavenger indicated data are bad 

630 The time passed to Delay_Time, Convert_Time, or Send_Event_Chn has 
invalid year 

631 Illegal timeout request parameter 
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632 No memory available to initialize clock 

634 Illegal timed event id of -1 

635 Process got unblocked prematurely due to process termination 

636 Timer request did not complete successfully 

638 Time passed to Deiay_Time or Send_Event_Chn more than 23 days from 
current time 

639 Illegal date passed to Set_Time, or illegal date from system clock in 
Get_Time 

640 RS-232 driver called with wrong version number 

641 RS-232 read or write initiated with illegal parameter 

642 Unimplemented or unsupported RS-232 driver function 

646 No memory available to initialize RS-232 

647 Unexpected RS-232 timer interrupt 

648 Unpermltted RS-232 initialization, or disconnect detected 

649 illegal device control parameters to RS-232 

652 N-port driver not initialized prior to ProFile 

653 No room in sysglobai to initialize ProFile 

654 Hard error status returned from drive 

655 Wrong call version to ProFile 

656 Unpermitted ProFile function 

657 Illegal device control parameter to ProFile 

658 Premature end of file when reading from driver 

659 Corrupt File System header chain found in driver 

660 Cable disconnected 

662 Parity error while sending command or writing data to ProFile 

663 Checksum error or CRC error or parity error in data read 
666 Timeout 

670 Bad command response from drive 

671 Illegal length specified (must -1 on input) 

672 Unimplemented console driver function 

673 No memory available to initialize console 

674 Console driver called with wrong version number 

675 Illegal device control 

680 Wrong call version to serial driver 

682 Unpermitted serial driver function 

683 No room in sysglobai to ir litialize serial driver 

685 Eject not allowed this device 

686 No room in sysglobai to initialize n-port card driver 

687 Unpermitted n-port card driver function 

688 Wrong call version to n-port card driver 

690 Wrong call version to parallel printer 

691 Illegal parallel printer parameters 

692 N-port card not initialized prior to parallel printer 

693 No room in sysglobai to initialize parallel printer 

694 unimplemented parallel printer function 

695 Illegal device control parameters (parallel printer) 

696 Printer out of paper 
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698 Printer offline 

699 No response from printer 

700 Mismatch Detween loader version number and Operating System version 
number 

701 OS exhausted its internal space during startup 

702 Cannot make system process 

703 Cannot kill pseudo-outer process 

704 Cannot create driver 

706 Cannot initialize floppy disk driver 

707 Cannot initialize the File System volume 

708 Hard disk mount table unreadable 
7 09 Cannot map screen data 

710 Too many slot-based devices 

724 The boot tracks do not know the right File System version 

725 Either damaged File System or damaged contents 

726 Boot device read failed 

727 The OS will not fit into the available memory 

728 SYSTEM.OS is missing 

729 SYSTEM.CONFIG is corrupt 

730 SYSTEM.OS is corrupt 

731 SYSTEM.DEBUG or SYSTEM.DEBUG2 is corrupt 

732 SYSTEM.LLD is corrupt 

733 Loader range error 

734 Wrong driver is found. For instance, storing a diskette loader on a ProFile 

735 SYSTEM.LLD is missing 

736 SYSTEM.UNPACK is missing 

737 Unpack of SYSTEM.OS with SYSTEM.UNPACK failed 

801 IOResult <> 0 on I/O using the Monitor 

802 Asynchronous 1/0 request not completed successfully 

803 Bad combination of mode parameters 
806 Page specified is out of range 

809 Invalid arguments (page, address, offset, or count) 

810 The requested page could not be read in 

816 Not enough sysglobal space for File System buffers 

819 Bad device number 

820 No space in sysglobal for asynchronous request list 

821 Already initialized 1/0 for this device 

822 Bad device number 

825 Error in parameter values (Allocate) 

826 No more room to al locate pages on device 

828 Error in parameter values (Deallocate) 

829 Partial deallocation only (ran into unallocated region) 

835 Invalid s-file number 

837 Unallocated s-file or I/O error 

838 Map overflow: s-file too large 

839 Attempt to compact file past PEOF 
841 Unallocated s-file or I/O error 
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843 Requested exact fit, but one could not oe provided 

847 Requested transfer count is <- 0 

848 End of file encountered 

849 Invalid page or offset value in parameter list 
852 Bad unit numDer 

854 No free slots in s-llst directory (too many s-files) 

855 No availaDle disk space for file hints 

856 Device not mounted 

857 Empty, locked, or invalid s-file 

861 Relative page is beyond PECF (bad parameter value) 

864 no sysgiobai space for volume bitmap 

866 Wrong FS version or not a valid Lisa FS volume 

867 Bad unit number 

868 Bad unit number 

869 Unit already mounted (mount)/no unit mounted 

870 No sysgiobai space for DCB or MDDF 

871 Parameter not a valid s-file ID 

872 No sysgiobai space for s- fi le control block 

873 Specified file is already open for private access 

874 Device not mounted 

875 invalid s-file ID or s-file control block 
879 Attempt to postion past LEOF 

881 Attempt to read empty file 

882 No space on volume for new data page of file 

883 Attempt to read past LEOF 

884 Not first auto-allocation, but file was empty 

885 Could not update filesize hints after a write 

886 No syslocal space for I/O request list 

887 catalog pointer does not indicate a catalog (bad parameter) 

888 Entry not found in catalog 

890 Entry by that name already exists 

891 Catalog is full or is damaged 

892 Illegal name for an entry 

894 Entry not found, or catalog is damaged 

895 invalid entry name 

896 Safety switch is on—cannot kill entry 

897 invalid bootdev value 

899 Attempt to allocate a pipe 

900 Invalid page count or FCB pointer argument 

901 Could not satisfy allocation request 

921 Pathname invalid or no such device 

922 invalid label size 

926 Pathname invalid or no such device 

927 Invalid label size 

941 Pathname invalid or no such device 

944 Object is not a file 

945 File is not in the killed state 
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946 Pathname invalid or no such device 

947 Not enough space in syslocal for File System refdb 

948 Entry not found in specified catalog 

949 Private access not allowed if file already open shared 

950 Pipe already in use, requested access not possible or dwrite not allowed 

951 File is already opened in private mode 

952 Bad refnum 

954 Bad refnum 

955 Read access not allowed to specified object 

956 Attempt to position FMARK past leof not allowed 

957 Negative request count is illegal 

958 Nonsequential access is not allowed 

959 System resources exhausted 

960 Error writing to pipe while an unsatisfied read was pending 

961 Bad refnum 

962 No WRITE or APPEND access allowed 

963 Attempt to position FMARK too far past LEOF 

964 Append access not allowed in absolute mode 

965 Append access not allowed in relative mode 

966 Internal inconsistency of FMARK and LEOF (warning) 

967 Nonsequential access is not allowed 

968 Bad refnum 

971 Pathname invalid or no such device 

972 Entry not found in specified catalog 
974 Bad refnum 

977 Bad refnum 

978 Page count Is nonpositive 

979 Not a block-structured device 

981 Bad refnum 

982 No space has been allocated for specified file 

983 Not a block-structured device 

985 Bad refnum 

986 No space has been allocated for specified file 

987 Not a block-structured device 

988 Bad refnum 

989 Caller is not a reader of the pipe 

990 Not a block-structured device 

994 invalid refnum 

995 Not a block-structured device 

999 Asynchronous read was unblocked before it was satisfied 

1021 Pathname invalid or no such entry 

1022 No such entry found 

1023 Invalid newname, check forin string 

1024 New name already exists in catalog 

1031 Pathname invalid or no such entry 

1032 Invalid transfer count 

1033 No such entry found 
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1041 Pathname invalid or no such entry 

1042 invalid transfer count 

1043 No such entry found 

1051 No device or volume by that name 

1052 A volume is already mounted on device 

1053 Attempt to mount temporarily unmounted boot volume just unmounted from 
this Lisa 

1054 The bad block directory of the diskette is invalid 

1061 No device or volume by that name 

1062 No volume is mounted on device 

1071 Not a valid or mounted volume for working directory 

1091 Pathname invalid or no such entry 

1092 No such entry found 
1101 Invalid device name 

1121 Invalid device, not mounted, or catalog is damaged 
1128 Invalid pathname, device, or volume not mounted 

1130 File is protected;cannot open due to protection violation 

1131 No device or volume by that name 

1132 No volume is mounted on that device 

1133 No more open files in the file list of that device 

1134 Cannot find space in sysglobal for open file list 

1135 Cannot find the open file entry to modify 

1136 Boot volume not mounted 

1137 Boot volume already unmounted 

1138 Caller cannot have higher priority than system processes when calling ubd 

1141 Boot volume was not unmounted when calling rbd 

1142 Some other volume still mounted on the boot device when calling rbd 

1143 No sysglobal space for MDDF to do rbd 

1144 Attempt to remount volume which is not the temporarily unmounted boot 
volume 

1145 No sysglobal space for bit map to do rbd 

1158 Track-by-track copy buffer is too small 

1159 Shutdown requested while boot volume was unmounted 

1160 Destination device too small for track-by-track copy 

1161 Invalid final shutdown mode 

1162 Power is already off 

1163 Illegal command 

1164 Device is not a diskette device 

1165 No volume is mounted on the device 

1166 A valid volume is already mounted on the device 

1167 Not a block-structured device 

1168 Device name is invalid 

1169 Could not access device before initialization using default device 
parameters 

1170 Could not mount volume after initialization 

1171 is not allowed in a volume name 

1172 No space available to initialize a bitmap for the volume 
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1176 Cannot read from a pipe more than naif of its allocated physical size 

1177 Cannot cancel a read request for a pipe 

1178 Process waiting for pipe data got unoiocked because last pipe writer closed 
it 

1180 Cannot write to a pipe more than naif of its allocated physical size 

1181 No system space left for request block for pipe 

1182 Writer process to a pipe got unblocked before the request was satisfied 

1183 Cannot cancel a write request for a pipe 

1184 Process waiting for pipe space got unoiocked because the reader closed trie 

pipe 

1186 Cannot allocate space to a pipe while it has data wrapped around 
1188 Cannot compact a pipe while it has data wrapped around 

1190 Attempt to access a page that is not allocated to the pipe 

1191 Bad parameter 

1193 Premature end of file encountered 

1196 Something is still open on device—cannot unmount 

1197 volume is not formatted or cannot be read 

1198 Negative request count is illegal 

1199 Function or procedure is not yet implemented 

1200 Illegal volume parameter 

1201 Blank file parameter 

1202 Error writing destination file 

1203 invalid UCSD directory 

1204 File not found 

1210 Boot track program not executable 

1211 Boot track program too big 

1212 Error reading boot track program 

1213 Error writing boot track program 

1214 Boot track program file not found 

1215 Cannot write boot tracks on that device 

1216 Could not create/close internal buffer 

1217 Boot track program has too many code segments 

1218 Could not find configuration information entry 

1219 Could not get enough working space 

1220 Premature EOF in boot track program 

1221 Position out of range 

1222 No device at that position 

1225 Scavenger has detected an internal inconsistency symptomatic of a software 
bug 

1226 Invalid device name 

1227 Device is not block structured 

1228 Illegal attempt to scavenge the boot volume 

1229 Cannot read consistently from the volume 

1230 Cannot write consistently to the volume 

1231 Cannot allocate space (Heap segment) 

1232 Cannot allocate space (Map segment) 

1233 Cannot allocate space (SFDB segment) 
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1237 Error rebuilding the volume root directory 

1240 Illegal attempt to scavenge a non-OS-formatted volume 

1296 Bad string argument has Deen passed 

1297 Entry name for the object is invalid (on the volume) 

1298 S-list entry for the object is invalid (on the volume) 

1807 No disk in floppy drive 

1820 Write-protect error on floppy drive 
1822 Unable to clamp floppy drive 
1824 Floppy drive write error 
1882 Bad response from ProFile 
1885 ProFile timeout error 

1998 Invalid parameter address 

1999 Badrefnum 

6001 Attempt to access unopened file 

6002 Attempt to reopen a file which is not closed using an open FIB (file info block) 

6003 Operation incompatible with access mode with which file was opened 

6004 Printer offline 

6005 File record type incompatible with character device (must be byte sized) 

6006 Bad integer (read) 

6010 Operation incompatible with file type or access mode 

6081 Premature end of exec file 

6082 invalid exec (temporary) file name 

6083 Attempt to set prefix with null name 

6090 Attempt to move console with exec or output file open 
6101 Bad real (read) 

6151 Attempt to reinitalize heap already in use 

6152 Bad argument to NE W (negati ve size) 

6153 Insufficient memory for NEW request 

6154 Attempt to RELEASE outside of heap 

Operating System Error Codes 

The error codes listed below are generated only when a nonrecoverable error 
occurs while in Operating System code. 

10050 Request block is not chained to a PCB (Unblk_Req) 

10051 Bld_Reo is called with interrupts off 

10100 An error was returned from SetUp_Directory or a Data Segment routine 
(Setup JUInfo) 

10102 Error > 0 trying to create shell (Root) 

10103 Sem_Count > 1 (Init_Sem) 

10104 Could not open event channel for shell (Root) 

10197 Automatic stack expansion fault occurred in system code (Check_Stack) 

10198 Need_Mem set for current process while scheduling is disabled 
(SimpleScheduler) 

10199 Attempt to block for reason other than I/O while scheduling is disabled 
(SimpleScheduler) 

10201 Hardware exception occurred while in system code 

10202 No space left from Sigl_Excep call in Hard_Excep 
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10203 No space left from Sigl_Excep call in Nmi_Excep 
10205 Error from wait_Event_Chn called in Excep_Prolog 

10207 No system data space in Excep_Setup 

10208 No space left from Sigl_Excep call in range error 

10212 Error in Term_Def_Hdl from EnaDle_Excep 

10213 Error in Force_Term_Excep, no space in Enq_Ex_Data 
10401 Error from Close_Event_Chn in Ec_Cleanup 

10582 Unable to get space in Freeze_Seg 
10590 Fatal memory parity error 

10593 Unable to move memory manager segment during startup 

10594 unable to swap in a segment during startup 

10595 unable to get space in Extend_MMlist 

10596 Trying to alter size of segment that is not data or stack (Alt_DS_Size) 

10597 Trying to allocate space to an allocated segment (Alloc_Mem) 

10598 Attempting to allocate a nonfree memory region (Take_Free) 

10600 Error attempting to make timer pipe 

10601 Error from Kill_Object of an existing timer pipe 

10602 Error f rom second Make_Pipe to make timer pipe 

10603 Error from Open to open timer pipe 

10604 No syslocal space for head of timer list 

10605 Error during allocate space for timer pipe, or interrupt from nonconfigured 
device 

10609 interrupt from nonconfigured device 

10610 Error from info about timer pipe 

10611 Spurious interrupt from floppy drive #2 

10612 Spurious interrupt from floppy drive #1, or no syslocal space for timer list 
element 

10613 Error from Read_Data of timer pipe 

10614 Actual returned from ReadjData is not the same as requested from timer 
pipe 

10615 Error from open of the receiver's event channel 

10616 Error from Write_Event to the receiver's event channel 

10617 Error from Close_Event_Chn on the receiver's pipe 
10619 No sysglobal space for timer request block 

10624 Attempt to shut down floppy disk controller while drive is still busy 
10637 Not enough memory to initialize system timeout drives 
10675 Spurious timeout on console driver 

10699 Spurious timeout on parallel printer driver 

10700 Mismatch between loader version number and Operating System version 
number 

10701 OS exhausted its internal space during startup 

10702 Cannot make system process 

10703 Cannot kill pseudo-outer process 

10704 Cannot create driver 

10706 cannot initialize floppy disk driver 

10707 Cannot initialize the File System volume 

10708 Hard disk mount table unreadable 
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10709 Cannot map screen data 

10710 Too many slot-based devices 

10724 The boot tracks do not know the right File System version 

10725 Either damaged File System or damaged contents 

10726 Boot device read failed 

10727 The OS will not fit into the available memory 

10728 SYSTEM.OS is missing 

10729 SYSTEM.C0NF1G is corrupt 

10730 SYSTEM.OS is corrupt 

10731 SYSTEM.DEBUG or SYSTEM.DEBUG2 is corrupt 

10732 SYSTEM.LLD is corrupt 

10733 Loader range error 

10734 wrong driver is found. For instance, storing a diskette loader on a ProFile 

10735 SYSTEM.LLD is missing 

10736 SYSTEM.UNPACK is missing 

10737 Unpack Of SYSTEM.OS with SYSTEM.UNPACK failed 

11176 Found a pending write request for a pipe while in Close_Object when it is 
called by the last writer of the pipe 

11177 Found a pending read request for a pipe while in Close_Object when it is 
called by the (only possible) reader of the pipe 

11178 Found a pending read request for a pipe while in Read_Data from the pipe 
11180 Found a pending write request for a pipe while in Write_Data to the pipe 
H8xx Error xx from diskette ROM (See OS errors I8xx) 

11901 Call to Getspace or Relspace with a bad parameter, or free pool is bad 
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* defined for mounted or unmounted devices 
$ defined for mounted devices only 
Ail other fields are defined for mounted block-structured devices only. 

DEVICE_L VOLUMEJ"; 


backup volid 

ID of the volume of which this volume is a copy. 

blocksize 

Number of bytes in a block on this device. 

* blockstructured 

Flag set if this device is block-structured. 

boot_code 

Reserved. 

boot_environ 

Reserved. 

clustersize 

Reserved. 

copy 

Reserved. 

copy_flag 

Flag set if this volume is a copy. 

copy_thread 

Count of copy operations involving this volume. 

datasize 

Number of data bytes in a page on this volume. 

* devt 

Device type. 

* dir_path 

Pathname of the volume/device. 

DTCC 

Date/time volume was created if it is a copy. 

DTVB 

Date/time volume was last backed-up. 

DTVC 

Date/time volume was created. 

DTVS 

Date/time volume was last scavenged. 

filecount 

Count of files on this volume. 

freecount 

Count of free pages on this volume. 

fs_overhead 

Number of pages on this volume required to store 
File System data structures. 

fs_size 

Number of pages on this volume. 

fsversion 

Version number of the File System under which 
this volume was initialized. 

-* iochannel 

Number of the expansion card channel through 
which this device is accessed. 

label_size 

Size in bytes of the user-defined labels associated 
with objects on this volume. 

$ lockeddev 

Reserved. 

machineJD 

Machine on which this volume was initialized. 

master 

Reserved. 

master_copy_ID 

Reserved. 

* mounted 

Flag set if a volume is mounted. 

$ mount_pending 

Reserved. 

* name 

Name of this volume/device. 

$ opencount 

Count of objects open on this volume/device. 

overmount_stamp 

Reserved. 

password 

Password of this volume. 
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$ privatedev 
privileged 
$ remote 
result_scavenge 
scavengejrag 

* slot_.no 

$ unmount_pending 
volid 

vol_left_mounted 

volname 

volnum 

vol_size 

write_protected 


0BJECT_T: 

acmode 

dirjoath 

DTA 

DTB 

DTC 

DTM 

DTS 

eof 

etype 

file_closed_by_OS 

file_left_open 

file_scavenged 

fmark 

fs_overhead 

ftype 

fuid 

kswitch 

locked 

lpsize 


Reserved. 

Reserved. 

Reserved. 

Reserved. 

Flag set Dy the Scavenger if it has altered this 
volume in some way. 

Number of the expansion slot holding the card 
through which this device is accessed. 

Reserved. 

Unique identifier for this volume. 

Flag set if this volume was mounted during a 
system crash. 

Volume name. 

Volume number. 

Total number of blocks in the File System volume 
and boot area on this device. 

Reserved. 


Set of access modes associated with this refnum. 
Pathname of the directory containing this object. 
Date/time object was last accessed. 

Date/time object was last backed-up. 

Date/time object was created. 

Date/time object was last modified. 

Date/time object was last scavenged. 

Flag set if end of file has been encountered on 
this object (through the given refnum). 

Directory entry type. 

Flag set if this object was closed by the Operating 
System. 

Flag set if this object was open during a system 
crash. 

Flag set by the Scavenger if this object has been 
altered in some way. 

Absolute byte to which the file mark points. 
Number of pages used by the File System to store 
control information about this object. 

Object type. 

Unique identifier for this object. 

Flag set when the object is killed. 

Reserved. 

Number of data bytes on a page. 
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machinejD 

master_file 

name 

nreaders 

nwriters 

nusers 

private 

protected 

psize 

refnum 

result_scavenge 

safety_on 

size 

system_type 

user_type 

user_subtype 


Machine on which this object may be opened. 
Flag set if this object is a master. 

Entry name of this object. 

Number of processes with this object open for 
reading. 

Number of processes with this object open for 
writing. 

Number of processes with this object open. 

Flag set if this object is open for private access. 
Flag set if this object is protected. 

Physical size of this object, in bytes. 

Reference number for this object (argument to 
INFO). 

Reserved. 

value of the safety switch for this object. 
Number of data bytes in this object (LEOF). 
Reserved. 

User-defined type field for this object. 
User-defined subtype field for this object. 
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Index 


Please note that the topic references in this Index are by section number. 


- A - 

accessing devices 1.3, 2.8 
ACTIVATE_PROCESS 3.8.6 
ALLOCATE 2.10.13 
Append access 2.10.8 
attribute 1.3, 2.10.5 


-- B - 

baud rate 2.10.12.1 
binding 4.1 
BINDJDATASEG 4.7.12 
blocked process 1.4, 

3 (introduction), 3.8.5 
buffer 2.9, 2.10.12.1, 2.10.16, 
5.5, 5.8 


-_ c - 

CARDSEQUIPPED 6.1.1 
catalog 2.1, 2.5, 2.10.19 
changing file size 2.10.13-2.10.15 
clock 5.6 

clock system calls 5.9 
CL0SE_DATASEG 4.7.4 
CLOSE_EVENT_CHN 5.8.4 
CLOSEJDBJECT 2.10.9 
code segment 4.5 

communication between processes 1.7 
COMPACT 2.10.14, 2.10.15 
configuration 6 (introduction) 
configuration system calls 6.1 
controlling 

a device 2.10.12 
a process 3.4 


C0NVERTJIME 5.9.4 

creating 

a data segment 4.7.1 
an event channel 5.8.1 
an object 2.10.1 
a process 3.3, 3.8.1 


- D - 

data segment 

creating 4.7.1 
private 4.1, 4.4 
shared 1.7, 4.1, 4.3 
swapping 4.6 
Decode mnemonics 2.10.12 
Dedata 2.10.12 
Detype 2.10.12 
Deversion 2.10.12 
DECLARE_EXCEP_H0L 5.7.1 
DELAY JIME 5.9.1 
deleting 

a process 3.8.2, 3.8.4 
an object 2.10.2 
device 2.3-2.7, 2.10.12 
accessing 1.3, 2.8 
control information 2.10.12 
mounting 1.3, 2.10.20 
names 2.1, 2.3, 2.10.12.1 
priority 2.3 
storage 2.4 
DEVICEC0NTR0L 2.10.12 
directory 2 (introduction) 
DISABLE_EXCEP 5.7.2 
disk hard error codes 2.10.12.2 
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division by zero 5.2, B 
Dread, Dwrite access 2.10.8 


- E - 

ENABLE_EXCEP 5.7.3 

end of file 2.7, 2.10.14, 2.10.15 

eof 2.10.5,- see also end of file. 

error 

disk hard error codes 2.10.12.2 
error messages D 
soft error 2.10.12.1 
See also exception, 
event 1.6, 5.4, C 
event channel 1.7, 5.5, 5.8.1 
event management system calls 5.8 
event types C 
exception 1.6, 5.1-5.3, B 
exception handler 5.1, 5.3 
exception management system calls 
5.7 

exception names 8 


-F- 

father process 1.4, 3.6, 3.7, 
3.8.1, 3.8.2 
file 2 (introduction) 
access 2.8 

attributes 2.10.5-2.10.7 
changing size 2.10.13-2.10.15 
label 2.6, 2.10.11 
marker 2.7, 2.10.15 
name 2.1, 2.10.1 
private 2.8 
shared 1.7, 2.8 
File System 1.3, 2 
File System calls 2.10 
FLUSH 2.10.16 


Index 


FLUSHJ5ATASEG 4.7.5 
FLUSH_EVENT_CHN 5.8.7 
FLUSH_EXCEP 5.7.6 
FS INFO fields E 


- G - 

GE TCONFI G_NAf1E 6.1.2 
GET_NEXT_ENTRY 2.10.19 
GETJIME 5.9.2 
GET_W0RKING_DIR 2.10.18 
global access to files 2.8 
global event channel 5.5 
Global Refnum 2.8, 2.10.8 


- H - 

handshake 2.10.12.1 
hierarchy of processes 3.2 


- 1 - 

INFO 2.10.6 
INF0_ADDRESS 4.7.9 
INF0_DATASEG 4.7.7 
INFO_EVENT_CHN 5.8.5 
INF0_EXCEP 5.7.4 
INF0_LDSN 4.7.8 
INF0_PR0CESS 3.8.3 
interface unit A 

interprocess communication 1.7, 2.9 
1/0 2 (introduction) 


- « - 

KILL_DATASEG 4.7.2 
KILL_EVENT_CHN 5.8.2 
KILL_08JECT 2.10.2 
KILL PROCESS 3.8.4 
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label, file 2.6, 2.10.11 
LDSN 4.2, 4.4, 4.7.8 
LEOF. See end of file, 
local data segment 4.1 
local event channel 5.5 
logical data segment number 4.2, 
4.4, 4.7.8 

logical end of file. See end of 
file. 

LOOKUP 2.10.5 


-H- 

MAKE DATASEG 4.7.1 

MAKE_EVENT__CHN 5.8.1 

MAKEFILE 2.10.1 

MAKE_PIPE 2.10.1 

MAKEPROCESS 3.8.1 

memory management 1.5, 4.1-4.6 

memory management system calls 4.7 

memory, parameter 6 (introduction) 

MEMJNFO 4.7.10 

mnemonics for Decode 2.10.12.1 

MOUNT 2.10.20 

mounting a device 1.3, 2.10.20 
MY ID 3.8.9 


- N - 

naming an object 2.1, 2.10.1, 
2.10.4 


- 0 - 

object 1.3 

creating 2.10.1 
deleting 2.10.2 
naming 2.1, 2.10.1 
renaming 2.10.4 


index 


OPEN 2.10.8 
0PEN_DATASEG 4.7.3 
0PEN_EVENT_CHN 5.8.3 
OS interface A 
0SB00TV0L 6.1.3 


-p- 

page 2.4 

parameter memory 6 (introduction) 
parity 2.10.12.1 
pathname 1.3, 2.1, 2.2 
PEOF. See end of file, 
physical end of file. See end of 
file. 

pipe 1.7, 2.9. 2.10.1, 2.10.8 
priority of devices 2.3 
priority of processes 3.5, 3.8.7, 
3.8.8 

private access to files 2.8, 2.10.8 
private data segment 4.1, 4.4 
process 1.4, 3 

blocked 1.4, 3 (introduction), 
3.8.5 

creating 3.3, 3.8.1 
father 1.4, 3.6, 3.7, 3.8.1, 
3.8.2 

hierarchy 3.2 
priority 3.5, 3.8.7, 3.8.8 
queuing 3.5, 3.8.5-3.8.8 
scheduling 3.5, 3.8.5-3.8.8 
shell 1.4, 3.2 
son 1.4, 3.7, C 
starting 3.8.1, 3.8.6 
stopping 3.8.2, 3.8.4 
structure 3.1 

termination 1.4, 3.6, 5.2, B, C 
process system calls 3.8 
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queuing a process 3.5, 3.8.5-3.8.8 


- R - 

range check error 5.2, B 
READ_DATA 2.10.10 
READJ_ABEL 2.10.11 
refnum 2.8; see also Global_Refnum. 
RENAME_ENTRY 2.10.4 
renaming an object 2.10.4 
RESET_CATAL0G 2.10.19 
running a program 1.4, 1.9, 3.8.1, 
3.8.6 


- s - 

safety switch 2.5, 2.10.17 
Scheduler 3 

scheduling processes 3.5, 

3.8.5-3.8.8 
SEND_EVENT_CHN 5.8.8 
SE T ACCE SSJD A T ASE G 4.7.11 
SETPRI0RITY_PR0CESS 3.8.7 
SET_FILE_INF0 2.10.7 
SET_LOCAl_TIME_DIFF 5.9.3 
SET_SAFETY 2.10.17 
SE T_W0RKING_DIR 2.10.18 
shared data segment 1.7, 4.1, 4.3 
shared file 1.7, 2.8 
shell process 1.4, 3.2 
SIGNAL_EXCEP 5.7.5 
SIZEJDATASEG 4.7.6 
soft error 2.10.12.1 
son process 1.4, 3.7, C 
sparing 2.10.12 

starting a process 3.8.1, 3.8.6 

stopping a process 3.8.2, 3.8.4 

storage device 2.4 
SUSPENDJTOCESS 3.8.5 


Index 


swapping 4.6 
Syscall unit A 
system calls 
clock 5.9 
configuration 6.1 
event management 5.8 
exception management 5.7 
file 2.10 

memory management 4.7 
process 3.8 
system clock 5.6, 5.9 
system-defined exceptions 5.2, B 
SYS0VERFL0W 5.2, 8 
SYS__SON_TERM C 
SYS_TERMINATE 5.2, B 
SYS_VALUE 00B 5.2, B 
SYS_ZER0_DIV 5.2, B 


- T - 

terminated process 1.4, 3.6, 5.2, 
B, C 

TERMINATE_PROCESS 3.8.2 
timed events 5.8.8 
tree, process 3.2 
TRUNCATE 2.10.15 


-y- 

UNBIND_DATASEG 4.7.12 
UNKILL_FILE 2.10.3 
UNMOUNT 2.10.20 

user-defined exception handler 5.3 


- v - 

value out of bounds 5.2, B 
volume catalog 2.1, 2.5, 2.10.19 
volume name 1.3 
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- w - 

WAIT_EVENT_CHN 5.8.6 
working directory 2.2 
working set 4.2 
WRITEJ)ATA 2.10.10 
WRITE_LABEL 2.10.11 
writing buffered data 2.10.16 


- Y - 

YIELO CPU 3.8.8 
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